dom1.0
The swift-dom library is a cross-platform, efficient, expressive DSL for generating HTML
(and related formats) with few intermediate allocations.
What's New
2024-04-22T21:52:11Z
The swift-dom library is a cross-platform, efficient, expressive DSL for generating HTML (and related formats) with few intermediate allocations.
$0[.li]
{
$0[.p] { $0.class = "album" } = "Tortured Poets Department"
}Why another HTML DSL?
Many HTML libraries are built around the idea of an Abstract Syntax Tree (AST). You build up a tree of nodes that represents the structure of the document, and then a rendering engine performs a tree traversal to generate the HTML. This is an intuitive mental model for many developers, and dovetails well with Swift result builders and Swift’s general ethos of immutable value semantics.
On the other hand, AST-based rendering can use a lot of memory, as it involves a large number of intermediate allocations. AST-based data structures also struggle with static typing, as they must balance the internal need to model the polymorphic nature of HTML nodes with the external need to present a type-safe API.
Many AST-based HTML libraries mitigate this problem by providing voluminous convenience APIs and multiple levels of abstraction, but these APIs do not always compose well, and can be difficult to learn. The large number of “concise” spellings also tends to trip up AI code generation tools who struggle to distinguish between real and imaginary APIs.
Philosophy
Swift DOM is designed to be composable and easy to learn, with a small number of patterns that developers must internalize. Instead of outlawing as many invalid states as possible at compile-time, Swift DOM relies on a small number of high-impact static typing rules to eliminate common mistakes without confusing developers with too many highly-specialized guardrails. The tradeoff is that some understanding of the HTML format is required to use Swift DOM correctly, as the library makes no effort to abstract away the underlying markup language.
Tutorials
We suggest reading the library tutorials to get started with the DSL.
Getting started with HTML in Swift
Using protocols with HTML in Swift
Using inline SVG with HTML in Swift
Who is using it?
The library has been in use on Swiftinit for over one year, and produces all of the HTML and SVG graphics on the site. Swift DOM 1.0 is our first attempt to open-source the DSL.
What platforms does it support?
Swift DOM is written in pure Swift, and works on Linux, macOS, iOS, watchOS, and tvOS. The HTML product does not link Foundation. You can view the full compatibility matrix on The Swift Package Index.
Swift DOM requires Swift 5.10.