This is just some html.
-My favorite cookie: ${vars.favoriteCookie}
-I love ${favoriteCake}!!
-About this site
', -} -``` - -#### Page definition array - -Export an array when the module always creates a fixed set of pages: - -```ts -// src/legal.pages.ts -export default [ - { - outputName: 'terms/index.html', - vars: { layout: 'legal', title: 'Terms' }, - children: 'Terms of service', - }, - { - outputName: 'privacy/index.html', - vars: { layout: 'legal', title: 'Privacy' }, - children: 'Privacy policy', - }, -] -``` - -#### Synchronous factory - -Export a function when definitions depend on declared global data or shared variables: - -```ts -// src/tag-indexes.pages.ts -export const dataDeps = ['tagIndex'] - -export default function tagIndexes ({ data }) { - return Object.entries(data.tagIndex).map(([tag, posts]) => ({ - outputName: `tags/${tag}/index.html`, - vars: { layout: 'tag-index', title: `Posts tagged ${tag}`, posts }, - })) -} -``` - -For a complete two-stage factory example, see [Generate yearly blog index pages](#generate-yearly-blog-index-pages). - -#### Asynchronous factory - -Export an async function when creating definitions requires asynchronous work: - -```ts -// src/team.pages.ts -import { readFile } from 'node:fs/promises' - -export default async function teamPages () { - const members = JSON.parse( - await readFile(new URL('./data/team.json', import.meta.url), 'utf8') - ) - - return members.map(member => ({ - outputName: `team/${member.slug}/index.html`, - vars: { layout: 'profile', title: member.name, member }, - })) -} -``` - -#### Async iterable - -Export an async generator when pages should be yielded incrementally: - -```ts -// src/archive.pages.ts -export const dataDeps = ['blogYears'] - -export default async function * archivePages ({ data }) { - for (const year of data.blogYears) { - yield { - outputName: `blog/${year}/index.html`, - vars: { layout: 'archive', year }, - } - } -} -``` - -### Generated-pages factory parameters - -Functions receive one object with: - -| Parameter | Contents | -|---|---| -| `vars` | Default and global vars. | -| `data` | Only the top-level values named by the module's `dataDeps` export. | -| `pagesFile` | Information about the current file. `name` is the filename without its `.pages.*` suffix, `path` is its source-relative directory, and `pagesFile` contains the underlying file information. | - -Factories do not receive raw source or generated `PageData` collections. -Put page-collection logic in `global.data.ts`, return a focused serializable value, and subscribe to its key from the factory. -This keeps factories downstream of source discovery without exposing generation order or creating page-generation cycles. - -### Generated page definitions - -| Field | Behavior | -|---|---| -| `outputName` | Output path relative to the pages file's directory. It must name a file, must not be absolute or contain `..` segments, and cannot end in a path separator. Defaults to `Hello from the post.
' -``` - -DOMStack renders `root(article(page()))`. -A root layout omits `parentLayout`; child layouts can name any discovered layout, including the bundled `root`. -Names are the same filename-derived names used by `vars.layout`, not import paths. -Missing parents, invalid parent exports, and cycles fail the build with the offending layout or chain. - -All renderers receive the same resolved vars, page metadata, worker URLs, and asset lists. -Vars merge from outermost to innermost layout, followed by page vars and builder/frontmatter vars. -Layout `vars.layout` does not select a parent; only the named `parentLayout` export establishes nesting. -Async layouts are awaited at every step, and intermediate values pass through unchanged until the final result is serialized. -Each parent must accept the kind of children its immediate child returns. - -#### Data subscriptions in nested layouts - -Each layout declares only the data it reads. -Keep focused consumer types beside their producer in `global.data.ts`: - -```typescript -// global.data.ts -export type RootLayoutData = { navigation: { title: string, url: string }[] } -export type ArticleLayoutData = { recentPosts: { title: string, url: string }[] } -export type GlobalData = RootLayoutData & ArticleLayoutData -``` - -```typescript -// root.layout.ts -import type { DataDeps } from '@domstack/static/types.js' -import type { RootLayoutData } from './global.data.ts' - -export const vars = { - dataDeps: ['navigation'] satisfies DataDepsRedirecting to ${vars.redirectTo}
- -`) -} -``` - -`redirectFrom` contains old same-origin public URL paths. `redirectOutputName()` converts directory URLs such as `/2020/old-slug/` to `2020/old-slug/index.html`. DOMStack's generated-output validation still rejects escaping paths such as `..`. The redirect target comes from the current page's normalized `pageInfo.url`, so moving the page again only requires retaining its previous URLs in that page's metadata. `fragtml` escapes interpolated values by default, including attribute values and link text. - -**SEO note:** Meta-refresh is a client-side redirect. Search engines may not treat it as a permanent 301 redirect. For static hosting platforms that support server-side redirects, you can instead generate a `_redirects` file (Netlify, Cloudflare Pages) or `vercel.json` (Vercel) using the object template type: - -```typescript -// src/redirects-netlify.txt.template.ts -// Generates a _redirects file for Netlify / Cloudflare Pages. - -export const dataDeps = ['redirects'] - -export default function ({ data }) { - return { - outputName: '_redirects', - content: data.redirects.map(({ from, to }) => `${from} ${to} 301`).join('\n'), - } -} -``` - -Both approaches can coexist and consume the same `global.data.ts` redirect collection. Copying a directory that contains a hand-crafted `_redirects` file via `--copy` is also an option when you prefer to manage redirects outside the build. - -## Implementation - -`domstack` bundles the best tools for every technology in the stack: - -- `js` and `css` is bundled with [`esbuild`](https://github.com/evanw/esbuild). -- `md` is processed with [markdown-it](https://github.com/markdown-it/markdown-it). -- static files are processed with [cpx2](https://github.com/bcomnes/cpx2). -- `ts` support via native typestripping in Node.js and esbuild. -- `jsx/tsx` support via esbuild. - -These tools are treated as implementation details, but they may be exposed more in the future. The idea is that they can be swapped out for better tools in the future if they don't make it. - -### Build Process Flow - -The following diagram illustrates the DomStack build process: - -``` - βββββββββββββββ - β START β - ββββββββ¬βββββββ - β - βΌ - ββββββββββββββββββββ - β identifyPages() β - β β - β β’ Find pages β - β β’ Find layouts β - β β’ Find templates β - β β’ Find globals β - β β’ Find settings β - ββββββββββ¬ββββββββββ - β - β - βββββββββββββββββββββΌββββββββββββββββββββ - β β β - βΌ βΌ βΌ -βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ -β buildEsbuild() β β buildStatic() β β buildCopy() β -β β β β β β -β β’ Bundle JS/CSS β β β’ Copy static β β β’ Copy extra β -β β’ Generate β β files β β directories β -β records β β β’ Record files β β β’ Record files β -ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ - β β β - βββββββββββββββββββββΌββββββββββββββββββββ - β - βΌ - ββββββββββββββββββββ - β buildPages() β - β β - β β’ Process HTML β - β β’ Process MD β - β β’ Process JS β - β β’ Apply layouts β - β β’ Record outputs β - ββββββββββ¬ββββββββββ - β - βΌ - ββββββββββββββββββββ - β Reconcile β - β Output Manifest β - ββββββββββ¬ββββββββββ - β - βΌ - ββββββββββββββββββββββββ - β Return Results β - β β - β β’ siteData β - β β’ esbuildResults β - β β’ staticResults β - β β’ copyResults β - β β’ pageBuildResults β - β β’ domstackManifest β - β β’ warnings β - ββββββββββββββββββββββββ -``` - -The build process follows these key steps: - -1. **Page identification** - Scans the source directory to identify all pages, layouts, templates, and global assets -2. **Destination preparation** - Ensures the destination directory is ready for the build output -3. **Parallel asset processing** - Three operations run concurrently and record their outputs: - - JavaScript and CSS bundling via esbuild - - Static file copying (when enabled) - - Additional directory copying (from `--copy` options) -4. **Page building** - Processes pages and normal templates, applying layouts and recording outputs -5. **Manifest reconciliation** - Normalizes recorded outputs, hashes file contents, filters entries, and computes a stable manifest version -6. **Return results** - Writes the manifest when enabled and returns all build results - -This architecture allows for efficient parallel processing of independent tasks while maintaining the correct build order dependencies. - -#### buildPages() Detail - -The `buildPages()` step processes pages in parallel with a concurrency limit: - -``` - ββββββββββββββββββββ - β buildPages() β - ββββββββββ¬ββββββββββ - β - ββββββββββΌββββββββββ - β Resolve Once: β - β β’ Global vars β - β β’ All layouts β - ββββββββββ¬ββββββββββ - β - ββββββββββββββΌββββββββββββββββ - β Parallel Page Init β - β(Concurrency: min(CPUs, 24))β - ββββββββββββββ¬ββββββββββββββββ - β - ββββββββββββββββββββββΌβββββββββββββββββββββ - β β β - βΌ βΌ βΌ -βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ -β MD Page Task β β HTML Page Task β β JS Page Task β -βββββββββββββββββββ€ βββββββββββββββββββ€ βββββββββββββββββββ€ -β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β -β β1. Parse MD β β β β1. Read .htmlβ β β β1. Import .jsβ β -β β frontmatter β β β β file β β β β module β β -β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β -β βΌ β β βΌ β β βΌ β -β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β -β β2. Variable β β β β2. Variable β β β β2. Variable β β -β β Resolution β β β β Resolution β β β β Resolution β β -β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β -β βΌ β β βΌ β β βΌ β -β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β -β β builder + β β β βpage.vars.js β β β β Exported β β -β β page.vars.jsβ β β β β β β β + page.varsβ β -β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β -βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ - β β β - ββββββββββββββββββββββββΌβββββββββββββββββββββββ - β - βΌ - βββββββββββββββββββββββββββββββ - β global.data.ts runs β - β (receives source PageData[])β - ββββββββββββββββ¬βββββββββββββββ - β - βΌ - βββββββββββββββββββββββββββββββ - β *.pages.* generates pages β - β using the derived data β - ββββββββββββββββ¬βββββββββββββββ - β - βΌ - βββββββββββββββββββββββββββββββββ - β Select data, render + write β - β (Concurrency: min(CPUs, 24)) β - βββββββββββββββββββββββββββββββββ -``` - -Variable Resolution Layers, from lowest to highest precedence: -- **Domstack defaults** - Internal defaults such as the default `layout: 'root'`. -- **Global vars** - Site-wide variables from `global.vars.js` (resolved once). -- **Layout vars** - Optional `export const vars` from the resolved layout chain, merged outermost to innermost. -- **Page-specific vars** vary by type: - - **MD pages**: `page.vars.js` plus builder vars from frontmatter. - - **HTML pages**: `page.vars.js`. - - **JS pages**: exported `vars` plus `page.vars.js`. - -Global data is not a variable-resolution layer. -It is resolved separately and projected into each consumer's `data` argument according to `dataDeps`. - -### Watch mode - -Running `domstack --watch` or `domstack -w` performs an initial build, watches the source inputs, and serves `dest` with live reload. Use `domstack --watch-only` when another process serves the output. - -Watch mode coordinates three independent watchers: - -- **esbuild** uses `context.watch()` for global, layout, and page client bundles, styles, page-scoped Web Workers, and the site service worker. -- **chokidar** watches page, layout, template, generated-pages, variable, and settings modules. DOMStack uses the changed file and its dependency maps to choose a rebuild scope. -- **cpx2** watches static assets under `src` and directories supplied with `--copy`, copying or removing their destination files directly. - -> [!NOTE] -> The filenames below use `.ts` by default. You can also use `.js`, and TypeScript client bundles can use `.tsx`. See [Supported file types](#supported-file-types) for all available extensions. - -DOMStack uses these rebuild scopes: - -- **esbuild only**: esbuild updates an existing browser entry without rendering HTML. -- **Targeted page/template rebuild**: DOMStack renders only the affected source-backed pages or templates. -- **Targeted generated-pages rebuild**: DOMStack renders and reconciles only the outputs owned by affected `*.pages.ts` files. -- **Full page/template rebuild**: DOMStack renders every source-backed and generated page and every template without restarting esbuild. -- **Full rebuild**: DOMStack rediscovers the source tree, restarts esbuild, renders all pages and templates, and refreshes its dependency maps. - -Like templates, generated-pages modules rebuild when their own source or imported dependencies change. -When a targeted build recomputes global data, DOMStack compares top-level values with the previous successful build and adds only subscribers of changed keys to the rebuild set. - -#### What triggers what - -| Change | Rebuild scope | -|---|---| -| Existing `page.ts`, `page.html`, `page.md`, or adjacent `page.vars.ts` | That page, plus subscribers of any changed global-data keys | -| A module imported by a TypeScript page or `page.vars.ts` | Pages that depend on it, plus subscribers of any changed global-data keys | -| Existing `*.layout.ts` or a module it imports | Source-backed pages and generated-page owners using the affected layout | -| Existing `*.template.ts` or a module it imports | Affected templates | -| Existing `*.pages.ts` | Generated outputs owned by that file, then refresh dependency maps | -| A module imported by `*.pages.ts` | Generated outputs owned by the importing files, then refresh dependency maps | -| `markdown-it.settings.ts` | All source-backed Markdown pages, plus subscribers of any changed global-data keys | -| `global.data.ts` | Consumers subscribed to top-level keys whose values changed | -| `global.vars.ts` or `esbuild.settings.ts` | Full rebuild | -| `domstack-manifest.settings.ts` | No rebuild. The manifest pipeline is disabled in watch mode | -| Existing client, style, Web Worker, or service-worker entry | esbuild only | -| Static asset under `src` or a file under a `--copy` directory | cpx2 copies or removes the output directly | - -Adding or removing a file changes the set of discovered build inputs: - -| Added or removed file | Rebuild scope | -|---|---| -| Site `service-worker.ts` | Restart esbuild. No page rebuild | -| `global.client.ts` or `global.css` | Restart esbuild and rebuild all pages | -| Layout client or style | Restart esbuild and rebuild source-backed pages and generated-page owners using that layout | -| Page client, style, or Web Worker | Restart esbuild and rebuild that page | -| Any other page, layout, template, generated-pages, variable, or settings file | Full rebuild | - -When a full page/template rebuild or targeted generated-pages rebuild no longer claims an output from the previous successful build, DOMStack removes that obsolete page or template output from `dest` without touching outputs owned by unaffected files. - -#### Dependency tracking - -DOMStack uses [`@11ty/dependency-tree-typescript`](https://github.com/11ty/dependency-tree-typescript) to statically analyze ESM imports. It maintains maps for: - -- Layout dependencies, source-backed pages using each layout, and generated-page owner layout membership -- TypeScript pages and adjacent page-variable dependencies -- Template dependencies -- Generated-pages module dependencies -- Current esbuild entry points - -The maps are created after the initial build and refreshed after structural or generated-pages rebuilds. Dependency analysis is best-effort. When DOMStack cannot safely determine a targeted scope, it falls back to a broader rebuild or skips an unrelated changed module. - -esbuild tracks browser-entry dependencies independently. Changing a module imported by `client.ts` rebundles that entry without rendering page HTML. - -#### Stable entry filenames - -Watch mode uses stable filenames for esbuild entry outputs: - -```text -[dir]/[name] -``` - -Production builds use content-hashed entry filenames: - -```text -[dir]/[name]-[hash] -``` - -Shared chunks remain content-hashed in both modes: - -```text -chunks/[ext]/[name]-[hash] -``` - -Page HTML points to stable entry files during watch mode. esbuild can update an entry and its chunk imports without requiring DOMStack to render the page again. - -#### Manifest behavior - -Watch mode builds and rebundles the site service worker, but it does not finalize, return, or write the [DOMStack manifest](#domstack-manifest). Changes to `domstack-manifest.settings.ts` therefore do not trigger a watch rebuild. - -Use `domstack --serve` when testing manifest-driven cache behavior. It runs a one-shot build and serves the result without watch-mode filenames or live-reload HTML injection. Add `--domstackManifest` only when the service worker or test needs the public `domstack-manifest.json` file. - -#### Build serialization - -Chokidar events are serialized through a promise chain. Each page rebuild or esbuild restart completes before the next queued filesystem event is processed, preventing overlapping DOMStack rebuilds during rapid saves. - -## Design goals - -DOMStack aims to make building a website feel like working directly with the web platform, with a small set of dependable conventions layered on top. - -### Be simple and dependable - -- Be boring, work well, and make the developer's job easier. -- Prefer convention over configuration. Configuration should be optional and minimal. -- Combine proven tools into one coherent system instead of reimplementing them. -- Avoid clever hacks, speculative abstractions, and complexity that becomes permanent maintenance work. -- Do not over-correct bad input. Clear inputs should produce predictable outputs. - -### Build on the web platform - -- HTML is the source of truth, and strings are the interchange format between rendering tools. -- Let browsers handle links, navigation, documents, and URLs. Do not add magic behavior to `` or `` elements or require client-side routing. -- Treat pages as shallow applications: each page starts as a new document and a blank canvas. Shared client state is possible, but not assumed. -- Remain library-agnostic. A page or layout is a program, so it can use tagged templates, a rendering library, or any other approach that returns the expected output. - -### Make structure visible - -- The source directory structure should mirror the site's URL structure. -- Every page should have an obvious entrypoint and build to an `index.html` in its corresponding directory, enabling clean URLs and reliable relative links. -- Keep pages and their assets colocated. Do not require parallel directory trees with matching structures. -- Support both `page.md` and `README.md` entrypoints. `README.md` keeps a source tree navigable on Git hosts, while `page.md` is available when repository navigation is not a concern. - -### Keep build steps orthogonal - -- Page rendering, static copying, and CSS and JavaScript bundling should remain independent build steps. -- Treat bundling as an optimization over a source tree that stays close to directly runnable web content. -- Keep entry filenames stable and conventional so each build input has an obvious purpose. -- Design independent steps so they can run concurrently when possible and rebuild only the outputs they affect. - -### Use standard language tooling - -- Use standard file types and syntax rather than framework-specific extensions or editor plugins. -- Use real TC39 ESM and prefer standard `.ts` and `.js` modules with `"type": "module"` over compatibility escape hatches. -- Support TypeScript through Node.js type stripping and JavaScript through JSDoc. Leave static type checking to `tsc`. -- Encourage directly runnable source modules. Language servers, formatters, linters, and debuggers should work without understanding a DOMStack-specific language. - -### Prefer durable choices - -- Build for the platform that exists now instead of simulating predicted future standards. -- Benefit from passive improvements to browsers, JavaScript, TypeScript, and Node.js by staying close to their conventions. -- Adopt ecosystem trends only when they solve a concrete problem better than the existing platform. - -## FAQ - -Why DOMStack? - -: DOMStack is named after the [DOM (Document Object Model)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) and the concept of stacking technologies together to build websites. It represents the layering of HTML, CSS, and JavaScript in a cohesive build system and its emphasis of using what we have rather than inventing brand new ideas or concepts. Also since I had to replace a Wallace and Gromit reference, it could maybe also double as a [cheeky](https://youtu.be/tiJ4ffGZ7cM?t=77) homage to Node's former legend `substack`. - -How does `domstack` relate to [`top-bun`](https://www.npmjs.com/package/top-bun)? - -: `top-bun` is the former name of `domstack` and was named after the bakery in Wallace & Gromit's [A Matter of Loaf and Death π](https://www.youtube.com/watch?v=zXBmZLmfQZ4) which my kids were watching at the time. The project and package were renamed to DOMStack and `@domstack/static` in v11. See the [`top-bun` to DOMStack migration guide](./docs/v11-migration.md) when updating an older project. The `bun` project took off -and hosed the projects chances at SEO! - -How does `domstack` relate to [`sitedown`](https://ghub.io/sitedown) - -: `top-bun` used to be called `siteup` which is sort of like "markup", which is related to "markdown", which inspired the project `sitedown` to which `domstack` is a spiritual off-shoot of. Put a folder of web documents in your `domstack` build system, and generate a website. `domstack` is definitely it's own thing now though! - - -Is this for real? - -: Yes! The frontend space is crowded and brutal, and full of repeat ideas. DOMStack started and will remain as an opensource-for-one project and my goal is to explore ideas that I haven't seen manifest in ways I would like to see elsewhere. -Usage and contribution is encouraged and welcome and appreciated of course. I already consider the project a success for the goals I set out to achieve with it and don't plan to growth hack it at all. - -## Project status - -DOMStack is actively developed and currently available as a v12 prerelease. Its core feature set includes: - -- Markdown, HTML, and TypeScript pages -- Layouts with colocated styles and client bundles -- Global, layout, and page-scoped variables -- Centralized global data processing -- Generated pages and templates -- Static assets and additional copy directories -- Progressive watch rebuilds with dependency tracking -- TypeScript, JavaScript, and client-bundle TSX support -- Page-scoped Web Workers and a site service worker -- The DOMStack build manifest -- A built-in development server powered by [`@domstack/sync`][domstack-sync] - -See the [GitHub roadmap](https://github.com/users/bcomnes/projects/3/) for planned work, or the [changelog](CHANGELOG.md) for completed changes. Issues, ideas, and examples of sites built with DOMStack are welcome. - -## Links - -- [CHANGELOG](CHANGELOG.md) -- [CONTRIBUTING](CONTRIBUTING.md) -- [Dependencies](dependencygraph.svg) -- [fragtml docs][fragtml-docs] - -## License +## License [MIT](LICENSE) - -[htm]: https://github.com/developit/htm -[fragtml]: https://www.npmjs.com/package/fragtml -[fragtml-docs]: https://github.com/bcomnes/fragtml#readme -[preact]: https://preactjs.com/ -[domstack-sync]: https://www.npmjs.com/package/@domstack/sync -[hb]: https://handlebarsjs.com -[esbuild]: http://esbuild.github.io -[neocities-img]: https://img.shields.io/website/https/domstack.neocities.org?label=neocities&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAGhlWElmTU0AKgAAAAgABAEGAAMAAAABAAIAAAESAAMAAAABAAEAAAEoAAMAAAABAAIAAIdpAAQAAAABAAAAPgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAAAueefIAAACC2lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS40LjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOk9yaWVudGF0aW9uPjE8L3RpZmY6T3JpZW50YXRpb24+CiAgICAgICAgIDx0aWZmOlBob3RvbWV0cmljSW50ZXJwcmV0YXRpb24+MjwvdGlmZjpQaG90b21ldHJpY0ludGVycHJldGF0aW9uPgogICAgICAgICA8dGlmZjpSZXNvbHV0aW9uVW5pdD4yPC90aWZmOlJlc29sdXRpb25Vbml0PgogICAgICAgICA8dGlmZjpDb21wcmVzc2lvbj4xPC90aWZmOkNvbXByZXNzaW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4Kpl32MAAABzBJREFUWAnFVwtwnFUV/v5//31ks5tsE9I8moS0iWETSNKUVpBKDKFQxtrCUIpacHQEGYk16FQHaZ3ajjqjOGWqOKUyMCl2xFoKhQJDBQftpOnAmDZoOyRNjCS1SdO8H5vXPv7rd/7NZvIipQjjmfn23Me555x77rnnv6sppTT8H0n/tG1rmlZIVBG+eW1JBD4t0GA8cYZQcS7ncXL7bFuYPfBJ9mlwtxg3bJoSTvx0tn7LAU48IJNE3GyBj9unrlJC2XRt4vGvLFGGrkXYDxEl03WyDyfRRoiHrxOfiBPU85bovPezi5pHnlmhHq5IsaLAXHhltgPXi+A0VE8X+Dht6lov+uw2rf/8nmIlDjQ+fp1yO/SYnaKYXoOC5QSu8trgddnND7rHv0EvOymwTcbnI867OZ5PLCOKiUIijQgS54nPE3hsfXog2WNY2Z+V5MDXVifjd3/ths/jquL0QyIj9EdC3V6UoLr25KurU73D0ieOEIniKbkc063EduLPRDcR2828/DOpzrbBp0ut3UsEBMe3X2PJuhw2sWHplgjkEViyyBGM93gcf3kkxVP2hNZ1sWfoLg7/jbttJC8jMgiLHHYj4EuIb81I9gQLM92O0iyH+9pUlZSdGDHCJjA0biI/zZ3NxIstsfjKpfFYmROHutYxDwduIo6JAxI6LIq3cSmtpCSg9jF3UsXuix2tHb3L7YZevHRx/FBZvrNzTaEnLTfFQHaSna6CSrghjbVMJzRbtC1KFqC1xT5xAFdnZdxPMcsBS1wpDLHhEoWpiXbj3R8mZ1zoT0Caz677PE4fdDunJYIzd2UtvoKfWwq9+PnRiwgMDd5RX/PGVRIBixLjbNNKpQaP1wO/NzYb47ON0yEzAhUJQjOYJhKFy9DybDcyk+y40DeSdOz5J+5h7CBAxDQdl1k7d5rGHWW74Cz/GdM0gQGSWrMwxTl0VBRSlnSmoblMjIel0zkgN+gKSDFl7G7YMm+C4d8Ix4pvQ4XGPpKC8snQ/vPfvYXiwPuy6tylK3RAFokTpuU/NF8u08dAzbkA/nCylyVeBOanJawJQpcGxjMkB04QdzS0j5ujQVNntZK5BSkwYaIvEEZmQgjm4AeweTOguRah4ZKJdbubeZwKaYl23HptNNQxZeMhE0fqBrDthXZraHTCtKydlF73cFhv67l8FGRnm55sQcGjZ/GTI50IN75kKdMTsywnzMmtj4XmhuDRP13Ag8+2YnA0GrVgWDFmwFld10dN03TXNg2jIMNlKfywn//0BXGyKWBNv904isj5GqjhdmjeJSjMzUDttmUYChpYnS+1ZiY9+IUUrCvxIS/Nic/tbAiOBBkBltoeGn9PRA+c6Jm5Yp5edrIDlWsWw09Ht23IgBrvQ+i9Zy1JcaKE1+zmZTp0c240i7LiwJIPXdPACMnmw9ZriOV2Czu/ES3v7izAdZlx0rw8SQLy/jtu/AEmstfhTP3fcUPRUkS6ziB0eh/M/hZovCkx6ugP4ccvtuO1+gGMMI9IfbGM289j6JSRY/8YEIbmSxM4enoA+2t60MuEm0NyA2xOuL5UDaPgXjQ0NODmW27DgVeOw5a3Dq6Nh2DLWcMnyOjU0v6RME63jloJOjnYZ0VAOozCb8kq4506fG4bOgZCU1fphe/m4osliZNrokwFA3Cs/A7sq6qsgU0bN+LwS9GE9Pv9cLvd8Ofn4Zl7wlC9zXRWSnmUnqvpDVY+1yZ38WgsAjKzX34kNF1DYeQtduLOFT4ceSRvjnFEQrClFMK2/FsIBALYu3evZfw2mxe/Yj1obGzExY4OfPmr98Hu38QCOSGqp+j3tT3RLAZek0SwiMlYxyjIFu6WgX3fzMGNufKonYd49kNGOspLrkdTUxMikQhS4r34tZGDZObEHkccdu3chQ0bNiDc/OoMBQdqe/HOv0aSONhBHJ5yYFLqR+QVoYjyPcT7+mJVLsZ5n988O4gTvHrfX5uKMimjzOJEewhbt25FZ2cnWlpaUF1djdcTR1A6NoH24BiC/E4IKSaiyMuX9OVT/Xh4f5tkn0R+Czc9MOdZzokHLGmuiLPr8qqViqKchqYObcmNvnCeLlajz9+uzGCAOpTiNVabN2+25ETWMAxVV1enzPEBS254X5GqWpsmHwqRkfP4OpdF8y/WmM4psJ3HIVuYMr7n/qwZz6uRp/xq4uQvuSxK4sTBgwfVjh07VH19veInWnW9+j11uDJdlebEj0zqaiC/gSum/gxN3QJOzCA6sIIDv2D0KlhdrWS9Jt2F9aU+FKQ7eeYKi3kaSaur4C29j98lE4P9XWg59z5OnXgDb7/1pvlOY7c5EbYKjug+RFTSeJ90pmi6N/O1KbiKeIqOtJFPhXl6m87OGae8hPoU8SSxaj7dMvahEeCiGUQjcm/LiHLCT8hbUsaGCKk2wqWWNxHykD1LA13kC9JHdmBBLf/D5H8By9d+IkwR5NMAAAAASUVORK5CYII= diff --git a/bin.js b/bin.js index b2d99a01..51dd27da 100755 --- a/bin.js +++ b/bin.js @@ -83,6 +83,10 @@ const options = { type: 'boolean', help: 'watch and build the src folder without serving', }, + verbose: { + type: 'boolean', + help: 'show debug logs, including the build tree and individual copy operations', + }, serve: { type: 'boolean', help: 'build once and serve the destination directory without watching', @@ -222,7 +226,7 @@ domstack eject actions: opts.copy = copyPaths.map(p => resolve(cwd, p)) } - const logger = createDomStackLogger() + const logger = createDomStackLogger(argv['verbose'] ? 'debug' : 'info') opts.logger = logger const domStack = new DomStack(src, dest, opts) /** @type {BsInstance | null} */ @@ -256,8 +260,9 @@ domstack eject actions: if (!argv['watch'] && !argv['watch-only']) { try { const results = await domStack.build() - logger.info(tree(generateTreeData(cwd, src, dest, results))) + logger.debug(tree(generateTreeData(cwd, src, dest, results))) logWarnings(logger, results?.warnings) + logger.info(`Built ${relative(cwd, src) || '.'} β ${relative(cwd, dest) || '.'}`) logger.info('\nBuild Success!\n\n') if (argv['serve']) { buildServer = await createServer({ @@ -277,7 +282,7 @@ domstack eject actions: } } if ('results' in err) delete err.results - logger.error(inspect(err, { depth: 999, colors: true })) + logger.error(formatDiagnostic(err, Boolean(process.stdout.isTTY))) logger.error('\nBuild Failed!\n\n') process.exit(1) } @@ -285,7 +290,7 @@ domstack eject actions: await domStack.watch({ serve: !argv['watch-only'], onInitialBuild: (initialResults) => { - logger.info(tree(generateTreeData(cwd, src, dest, initialResults))) + logger.debug(tree(generateTreeData(cwd, src, dest, initialResults))) logWarnings(logger, initialResults?.warnings) }, }) @@ -315,12 +320,29 @@ function logWarnings (logger, warnings) { if ('message' in warning) { logger.warn(` ${warning.message}`) } else { - logger.warn(inspect(warning, { depth: 999, colors: true })) + logger.warn(formatDiagnostic(warning, Boolean(process.stdout.isTTY))) } } } +/** + * Keep nested causes, locations, and every diagnostic visible in CLI output. + * @param {unknown} value + * @param {boolean} colors + */ +function formatDiagnostic (value, colors) { + return inspect(value, { + depth: null, + maxArrayLength: null, + maxStringLength: null, + colors, + }) +} + run().catch(err => { - console.error(new Error('Unhandled domstack error', { cause: err })) + console.error(formatDiagnostic( + new Error('Unhandled domstack error', { cause: err }), + Boolean(process.stderr.isTTY) + )) process.exit(1) }) diff --git a/browser-tests/docs-diagrams.spec.js b/browser-tests/docs-diagrams.spec.js new file mode 100644 index 00000000..7022ad7c --- /dev/null +++ b/browser-tests/docs-diagrams.spec.js @@ -0,0 +1,21 @@ +import { resolve } from 'node:path' +import { expect, test, websiteOptions } from './support.js' + +test.use({ + siteSrc: resolve(import.meta.dirname, '..'), + siteOptions: websiteOptions, +}) + +test('the built documentation loads Mermaid and renders diagrams without errors', async ({ page, siteURL }) => { + const errors = [] + page.on('pageerror', error => errors.push(error.message)) + await page.goto(`${siteURL}/docs/implementation/`) + const diagrams = page.locator('.mermaid') + await expect(diagrams.first()).toBeVisible() + for (const diagram of await diagrams.all()) { + await expect(diagram.locator('svg')).toBeVisible() + // Mermaid may render an error SVG without throwing a JavaScript error. + await expect(diagram.locator('.error-icon')).toHaveCount(0) + } + expect(errors).toEqual([]) +}) diff --git a/browser-tests/docs-navigation.spec.js b/browser-tests/docs-navigation.spec.js new file mode 100644 index 00000000..dacdf2b6 --- /dev/null +++ b/browser-tests/docs-navigation.spec.js @@ -0,0 +1,163 @@ +import { resolve } from 'node:path' +import { expect, test, websiteOptions } from './support.js' + +test.use({ + siteSrc: resolve(import.meta.dirname, '..'), + siteOptions: websiteOptions, +}) + +test('an index section link navigates and selects the matching sidebar entry', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 1500, height: 900 }) + await page.goto(`${siteURL}/docs/`) + await page.locator('.docs-index a[href="layouts/#declaring-nested-layouts"]').click() + await expect(page).toHaveURL(`${siteURL}/docs/layouts/#declaring-nested-layouts`) + const nav = page.getByRole('navigation', { name: 'Documentation', exact: true }) + await expect(nav.locator('a[aria-current="page"]')).toHaveText('Layouts') + await expect(nav.locator('a[aria-current="location"]')).toHaveText('Declaring nested layouts') +}) + +test('disclosure arrows animate around a stable center and respect reduced motion', async ({ page, siteURL }) => { + await page.emulateMedia({ reducedMotion: 'no-preference' }) + await page.setViewportSize({ width: 1500, height: 900 }) + await page.goto(`${siteURL}/docs/layouts/`) + const summary = page.locator('.docs-navigation summary').filter({ has: page.getByRole('link', { name: 'CLI', exact: true }) }) + const arrowStyle = () => summary.locator('.docs-navigation-chevron').evaluate(element => { + const style = getComputedStyle(element) + return { + width: parseFloat(style.width), + height: parseFloat(style.height), + origin: style.transformOrigin, + transform: style.transform, + duration: style.transitionDuration, + + } + }) + const closed = await arrowStyle() + expect(closed.duration).toBe('0.2s') + expect(closed.width).toBe(16) + expect(closed.height).toBe(16) + const bounds = await summary.boundingBox() + await summary.click({ position: { x: bounds.width - 16, y: bounds.height / 2 } }) + await expect(summary.locator('..')).toHaveAttribute('open', '') + await expect.poll(async () => (await arrowStyle()).transform).not.toBe(closed.transform) + const opened = await arrowStyle() + expect(opened.width).toBe(closed.width) + expect(opened.height).toBe(closed.height) + expect(opened.origin).toBe(closed.origin) + expect(opened.transform).not.toBe(closed.transform) + + await page.emulateMedia({ reducedMotion: 'reduce' }) + await expect.poll(async () => (await arrowStyle()).duration).toBe('0s') +}) + +test('global bundles and cookbook subpages are linked from the documentation', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 1500, height: 900 }) + await page.goto(`${siteURL}/docs/`) + await page.locator('.docs-index a[href="global-bundles/"]').click() + await expect(page.locator('.docs-content > h1')).toHaveText('Global bundles') + await expect(page.locator('.docs-navigation a[aria-current="page"]')).toHaveText('Global bundles') + + await page.goto(`${siteURL}/docs/cookbook/`) + const recipes = await page.locator('.docs-content > ul > li > a').evaluateAll(links => links.map(link => ({ + href: link.href, + title: link.textContent, + }))) + expect(recipes).toHaveLength(4) + for (const recipe of recipes) { + const response = await page.goto(recipe.href) + expect(response.status()).toBe(200) + await expect(page.locator('.docs-content > h1')).toHaveText(recipe.title) + await expect(page.locator('.docs-navigation a[aria-current="page"]')).toHaveText(recipe.title) + await expect(page.locator('.docs-navigation nav > ul > li > details[open] > summary')).toHaveText('Recipes') + await expect(page.locator('.docs-navigation nav > ul > li > details[open] > ul > li > a[aria-current="page"]')).toHaveText(recipe.title) + await page.getByRole('link', { name: 'All recipes', exact: true }).click() + await expect(page).toHaveURL(`${siteURL}/docs/cookbook/`) + } +}) + +test('mobile navigation manages focus, section links, and return to desktop', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 390, height: 844 }) + await page.goto(`${siteURL}/docs/layouts/`) + const toggle = page.getByRole('button', { name: 'Open documentation menu' }) + const menu = page.getByRole('dialog', { name: 'Documentation', exact: true }) + const close = menu.getByRole('button', { name: 'Close documentation menu' }) + await toggle.focus() + await page.keyboard.press('Enter') + await expect(menu).toBeVisible() + await expect(toggle).toHaveAttribute('aria-expanded', 'true') + await expect(close).toBeFocused() + // Opening the modal must prevent focus from escaping into the page. + await toggle.evaluate(el => el.focus()) + await expect(close).toBeFocused() + await page.keyboard.press('Escape') + await expect(menu).toBeHidden() + await expect(toggle).toBeFocused() + await expect(toggle).toHaveAttribute('aria-expanded', 'false') + + await toggle.click() + await menu.getByRole('link', { name: 'Layout module exports', exact: true }).click() + await expect(menu).toBeHidden() + await expect(page).toHaveURL(`${siteURL}/docs/layouts/#layout-module-exports`) + await expect(page.locator('#layout-module-exports')).toBeFocused() + expect(await page.locator('html').evaluate(el => getComputedStyle(el).overflow)).not.toBe('hidden') + + // Resizing an open menu must restore navigation without leaving a modal or + // scroll lock behind. The restored links must still work. + await toggle.click() + await page.setViewportSize({ width: 1500, height: 900 }) + await expect(menu).toBeHidden() + await expect(toggle).toBeHidden() + const nav = page.getByRole('navigation', { name: 'Documentation', exact: true }) + await expect(nav).toBeVisible() + await expect(nav).toHaveCount(1) + expect(await page.locator('html').evaluate(el => getComputedStyle(el).overflow)).not.toBe('hidden') + await nav.getByRole('link', { name: 'CLI', exact: true }).click() + await expect(page).toHaveURL(`${siteURL}/docs/cli/`) +}) + +test('migration links support pointer navigation', async ({ page, siteURL }) => { + await page.goto(`${siteURL}/docs/migrations/`) + for (const version of ['v12', 'v11']) { + await page.locator('.docs-content > ul').getByRole('link', { name: `${version} migration`, exact: true }).click() + await expect(page).toHaveURL(`${siteURL}/docs/migrations/${version}-migration.html`) + await page.getByRole('link', { name: 'All migrations', exact: true }).click() + await expect(page).toHaveURL(`${siteURL}/docs/migrations/`) + } +}) + +test.describe('without JavaScript', () => { + test.use({ javaScriptEnabled: false }) + + test('migration guides are nested and linked through the migrations page', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 1500, height: 900 }) + await page.goto(`${siteURL}/docs/`) + await page.locator('.docs-index > ul > li > a[href="migrations/"]').focus() + await page.keyboard.press('Enter') + await expect(page.locator('.docs-content > h1')).toHaveText('Migrations') + for (const version of ['v12', 'v11']) { + await page.locator('.docs-content > ul').getByRole('link', { name: `${version} migration`, exact: true }).focus() + await page.keyboard.press('Enter') + await expect(page).toHaveURL(`${siteURL}/docs/migrations/${version}-migration.html`) + await expect(page.locator('.docs-content > h1')).toHaveText(`${version} migration`) + await expect(page.locator('.docs-navigation a[aria-current="page"]')).toHaveText(`${version} migration`) + await expect(page.locator('.docs-navigation nav details[open] > summary')).toHaveText('Migrations') + await expect(page.locator('.docs-breadcrumb').getByRole('link', { name: 'migrations', exact: true })).toHaveAttribute('href', './') + await page.getByRole('link', { name: 'All migrations', exact: true }).focus() + await page.keyboard.press('Enter') + await expect(page).toHaveURL(`${siteURL}/docs/migrations/`) + } + }) + + test('the server-rendered index and mobile navigation remain usable', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 390, height: 844 }) + await page.goto(`${siteURL}/docs/`) + await page.locator('.docs-index a[href="layouts/#declaring-nested-layouts"]').click() + await expect(page).toHaveURL(`${siteURL}/docs/layouts/#declaring-nested-layouts`) + await expect(page.getByRole('button', { name: 'Open documentation menu' })).toBeHidden() + const nav = page.locator('.docs-navigation') + await expect(nav).toBeVisible() + await nav.getByRole('link', { name: 'CLI', exact: true }).focus() + await page.keyboard.press('Enter') + await expect(page).toHaveURL(`${siteURL}/docs/cli/`) + }) +}) diff --git a/browser-tests/docs-scroll.spec.js b/browser-tests/docs-scroll.spec.js new file mode 100644 index 00000000..f07b510f --- /dev/null +++ b/browser-tests/docs-scroll.spec.js @@ -0,0 +1,196 @@ +import { resolve } from 'node:path' +import { expect, test, websiteOptions } from './support.js' + +test.use({ + siteSrc: resolve(import.meta.dirname, '..'), + siteOptions: websiteOptions, +}) + +// Wait for native smooth scrolling as well as browsers that restore instantly. +async function waitForScrollToSettle (page) { + await page.evaluate(() => new Promise(resolve => { + let timer + const finish = () => { + removeEventListener('scroll', reset) + resolve() + } + const reset = () => { + clearTimeout(timer) + timer = setTimeout(finish, 200) + } + addEventListener('scroll', reset, { passive: true }) + reset() + })) +} + +test('the breadcrumb spans only the docs column and keeps its text aligned while sticky', async ({ page, siteURL }) => { + await page.goto(`${siteURL}/docs/pages/`) + for (const width of [390, 1100, 1500, 2000]) { + await page.setViewportSize({ width, height: 900 }) + for (const top of [0, 900]) { + await page.evaluate(top => scrollTo({ top, behavior: 'instant' }), top) + const geometry = await page.evaluate(() => { + const shell = document.querySelector('.docs-shell').getBoundingClientRect() + const content = document.querySelector('.docs-content') + const style = getComputedStyle(content) + const bounds = content.getBoundingClientRect() + const breadcrumb = document.querySelector('.docs-breadcrumb').getBoundingClientRect() + const text = document.querySelector('.docs-breadcrumb ol').getBoundingClientRect() + return { + left: breadcrumb.left, + expectedLeft: bounds.left + parseFloat(style.borderLeftWidth), + right: breadcrumb.right, + expectedRight: shell.right, + textLeft: text.left, + expectedTextLeft: bounds.left + parseFloat(style.borderLeftWidth) + parseFloat(style.paddingLeft), + top: breadcrumb.top, + stickyTop: parseFloat(getComputedStyle(document.querySelector('.docs-breadcrumb')).top), + overflow: document.documentElement.scrollWidth > document.documentElement.clientWidth, + } + }) + expect(Math.abs(geometry.left - geometry.expectedLeft)).toBeLessThan(1) + expect(Math.abs(geometry.right - geometry.expectedRight)).toBeLessThan(1) + expect(Math.abs(geometry.textLeft - geometry.expectedTextLeft)).toBeLessThan(1) + expect(geometry.overflow).toBe(false) + if (top) expect(Math.abs(geometry.top - geometry.stickyTop)).toBeLessThan(1) + } + } +}) + +test('reading position updates the URL, sidebar, and breadcrumb without navigating', async ({ page, siteURL }) => { + test.setTimeout(30_000) + await page.setViewportSize({ width: 1500, height: 900 }) + const base = `${siteURL}/docs/pages/?reading=test` + await page.goto(`${base}#page-styles`) + await page.evaluate(async () => { + await document.fonts.ready + }) + await waitForScrollToSettle(page) + await page.evaluate(() => { + history.replaceState({ preserved: true }, '', location.href) + document.getElementById('docs-content').focus({ preventScroll: true }) + }) + const length = await page.evaluate(() => history.length) + const section = page.locator('.docs-navigation a[aria-current="location"]') + const breadcrumb = page.locator('.docs-breadcrumb-section a') + await expect(section).toHaveText('Page Styles') + await expect(breadcrumb).toHaveText('Page Styles') + await expect(breadcrumb).toHaveAttribute('href', '#page-styles') + await expect(breadcrumb).toHaveAttribute('aria-current', 'location') + await expect(page.locator('.docs-breadcrumb [aria-current]')).toHaveCount(1) + const itemStyles = await page.locator('.docs-breadcrumb li > a').evaluateAll(links => links.map(link => { + const style = getComputedStyle(link) + const bounds = link.getBoundingClientRect() + return { + color: style.color, + font: style.font, + decoration: style.textDecorationLine, + top: bounds.top, + inset: bounds.left - link.parentElement.getBoundingClientRect().left, + } + })) + const original = itemStyles[1] + const added = itemStyles.at(-1) + expect(added.color).toBe(original.color) + expect(added.font).toBe(original.font) + expect(added.decoration).toBe(original.decoration) + expect(added.top).toBeCloseTo(original.top, 1) + expect(added.inset).toBeCloseTo(original.inset, 1) + + const scrollToHeading = async locator => { + return locator.evaluate(heading => { + const offset = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) + scrollTo({ top: scrollY + heading.getBoundingClientRect().top - offset + 2, behavior: 'instant' }) + return scrollY + }) + } + const y = await scrollToHeading(page.locator('#page-client-bundles')) + await expect(page).toHaveURL(`${base}#page-client-bundles`) + await expect(section).toHaveText('Page client bundles') + await expect(breadcrumb).toHaveText('Page client bundles') + expect(await page.evaluate(() => ({ + y: scrollY, length: history.length, state: history.state, focus: document.activeElement.id, + }))).toEqual({ y, length, state: { preserved: true }, focus: 'docs-content' }) + + // A real wheel scroll across the boundary also selects the preceding section. + await page.mouse.move(1400, 400) + await page.mouse.wheel(0, -100) + await expect(page).toHaveURL(`${base}#page-styles`) + await expect(section).toHaveText('Page Styles') + + // h4 has a URL of its own but keeps the parent h3 selected in the shared ToC. + const deeper = page.locator('#docs-content h4').filter({ hasText: '.tsx' }) + const id = await deeper.getAttribute('id') + await scrollToHeading(deeper) + await expect(page).toHaveURL(`${base}#${encodeURIComponent(id)}`) + await expect(section).toHaveText('Page client bundles') + await expect(breadcrumb).toHaveText('.tsx') + await expect(breadcrumb).toHaveAttribute('href', `#${encodeURIComponent(id)}`) + + // Scrolling upwards selects the preceding section, then clears the fragment. + await scrollToHeading(page.locator('#page-styles')) + await expect(page).toHaveURL(`${base}#page-styles`) + await expect(section).toHaveText('Page Styles') + await page.evaluate(() => scrollTo({ top: 0, behavior: 'instant' })) + await expect(page).toHaveURL(base) + await expect(section).toHaveCount(0) + await expect(breadcrumb).toHaveCount(0) + await expect(page.locator('.docs-breadcrumb [aria-current="page"]')).toHaveText('pages') + expect(await page.evaluate(() => history.length)).toBe(length) +}) + +test('long breadcrumb headings are safe text and truncate on mobile without growing the bar', async ({ page, siteURL }) => { + await page.setViewportSize({ width: 390, height: 844 }) + await page.goto(`${siteURL}/docs/pages/`) + const bar = page.locator('.docs-breadcrumb') + const initialHeight = (await bar.boundingBox()).height + const title = 'A long section heading with markup, detailed explanations, and many additional words' + await page.locator('#page-styles').evaluate((heading, title) => { + heading.textContent = title + location.hash = heading.id + }, title) + const breadcrumb = page.locator('.docs-breadcrumb-section a') + await expect(breadcrumb).toHaveText(title) + await expect(breadcrumb).toHaveAttribute('title', title) + await expect(breadcrumb.locator('em')).toHaveCount(0) + expect(await breadcrumb.evaluate(link => link.scrollWidth > link.clientWidth)).toBe(true) + expect((await bar.boundingBox()).height).toBeCloseTo(initialHeight, 1) + expect(await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth)).toBe(false) +}) + +test('explicit anchors and Back/Forward win over pending reading-position updates', async ({ page, siteURL }) => { + test.setTimeout(30_000) + await page.goto(`${siteURL}/docs/layouts/#declaring-nested-layouts`) + await page.evaluate(async () => { + await document.fonts.ready + }) + await waitForScrollToSettle(page) + const first = page.url() + const breadcrumb = page.locator('.docs-breadcrumb-section a') + await expect(breadcrumb).toHaveText('Declaring nested layouts') + // Schedule a reading-position update, then navigate before its timer fires. + await page.locator('#layout-variables').evaluate(async heading => { + heading.scrollIntoView({ behavior: 'instant' }) + await new Promise(resolve => requestAnimationFrame(resolve)) + }) + // A link near the bottom cannot necessarily align its heading with the top. + await page.locator('.docs-navigation a[href="./#custom-layout-renderers"]').click() + const second = `${siteURL}/docs/layouts/#custom-layout-renderers` + await expect(page).toHaveURL(second) + await expect(breadcrumb).toHaveText('Custom layout renderers') + await waitForScrollToSettle(page) + await page.waitForTimeout(450) + await expect(page).toHaveURL(second) + await page.goBack() + await expect(page).toHaveURL(first) + await expect(breadcrumb).toHaveText('Declaring nested layouts') + await waitForScrollToSettle(page) + await page.waitForTimeout(450) + await expect(page).toHaveURL(first) + await page.goForward() + await expect(page).toHaveURL(second) + await expect(breadcrumb).toHaveText('Custom layout renderers') + await waitForScrollToSettle(page) + await page.waitForTimeout(450) + await expect(page).toHaveURL(second) +}) diff --git a/browser-tests/support.js b/browser-tests/support.js index 8fd7777d..44be3247 100644 --- a/browser-tests/support.js +++ b/browser-tests/support.js @@ -4,6 +4,12 @@ import { createServer } from 'node:http' import { extname, resolve, sep } from 'node:path' import { testBuild } from '../index.js' +// Exercise the website's real exclusions, rather than maintaining a second list. +const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) +export const websiteOptions = { + ignore: pkg.scripts['build:domstack'].match(/--ignore (\S+)/)[1].split(','), +} + const fixtureSrc = resolve(import.meta.dirname, '../test-cases/general-features/src') const contentTypes = new Map([ ['.css', 'text/css; charset=utf-8'], @@ -13,8 +19,10 @@ const contentTypes = new Map([ ]) export const test = base.extend({ - siteURL: async ({ context }, use) => { - const build = await testBuild(fixtureSrc) + siteSrc: [fixtureSrc, { option: true }], + siteOptions: [{}, { option: true }], + siteURL: async ({ context, siteSrc, siteOptions }, use) => { + const build = await testBuild(siteSrc, siteOptions) const publicDir = build.dest const server = createServer(async (request, response) => { try { diff --git a/declaration.tsconfig.json b/declaration.tsconfig.json index 95ed7a6f..16032129 100644 --- a/declaration.tsconfig.json +++ b/declaration.tsconfig.json @@ -9,5 +9,6 @@ "exclude": [ "**/*.test.js", "test-cases/**/*", + "site/**/*", ] } diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..d76d7c0d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +--- +layout: docs +dataDeps: + - docsIndexHtml +--- + +# Documentation + +[DOMStack](../) builds websites from ordinary HTML, Markdown, CSS, and JavaScript files. +Start with [Core concepts](../#core-concepts), then follow [Installation and first build](../#installation-and-first-build). +Use these references as your project grows. + + +{{{ data.docsIndexHtml }}} diff --git a/docs/about/README.md b/docs/about/README.md new file mode 100644 index 00000000..af9bb3e1 --- /dev/null +++ b/docs/about/README.md @@ -0,0 +1,122 @@ +--- +layout: docs +docsOrder: 150 +handlebars: false +--- + +# About + +DOMStack is a static site builder centered on ordinary files, standard web technologies, and a small set of conventions. +These design goals explain its approach and the tradeoffs behind its features. + +## Table of Contents + +[[toc]] + +## Design goals + +DOMStack aims to make building a website feel like working directly with the web platform, with a small set of dependable conventions layered on top. + +### Be simple and dependable + +- Be boring, work well, and make the developer's job easier. +- Prefer convention over configuration. + Configuration should be optional and minimal. +- Combine proven tools into one coherent system instead of reimplementing them. +- Avoid clever hacks, speculative abstractions, and complexity that becomes permanent maintenance work. +- Do not over-correct bad input. + Clear inputs should produce predictable outputs. + +### Build on the web platform + +- HTML is the source of truth, and strings are the interchange format between rendering tools. +- Let browsers handle links, navigation, documents, and URLs. + Do not add magic behavior to `` or `` elements or require client-side routing. +- Treat pages as shallow applications: each page starts as a new document and a blank canvas. + Shared client state is possible, but not assumed. +- Remain library-agnostic. + A page or layout is a program, so it can use tagged templates, a rendering library, or any other approach that returns the expected output. + +### Make structure visible + +- The source directory structure should mirror the site's URL structure. +- Every page should have an obvious entrypoint and build to an `index.html` in its corresponding directory, enabling clean URLs and reliable relative links. +- Keep pages and their assets colocated. + Do not require parallel directory trees with matching structures. +- Support both `page.md` and `README.md` entrypoints. + `README.md` keeps a source tree navigable on Git hosts, while `page.md` is available when repository navigation is not a concern. + +### Keep build steps orthogonal + +- Page rendering, static copying, and CSS and JavaScript bundling should remain independent build steps. +- Treat bundling as an optimization over a source tree that stays close to directly runnable web content. +- Keep entry filenames stable and conventional so each build input has an obvious purpose. +- Design independent steps so they can run concurrently when possible and rebuild only the outputs they affect. + +### Use standard language tooling + +- Use standard file types and syntax rather than framework-specific extensions or editor plugins. +- Use real TC39 ESM and prefer standard `.ts` and `.js` modules with `"type": "module"` over compatibility escape hatches. +- Support TypeScript through Node.js type stripping and JavaScript through JSDoc. + Leave static type checking to `tsc`. +- Encourage directly runnable source modules. + Language servers, formatters, linters, and debuggers should work without understanding a DOMStack-specific language. + +### Prefer durable choices + +- Build for the platform that exists now instead of simulating predicted future standards. +- Benefit from passive improvements to browsers, JavaScript, TypeScript, and Node.js by staying close to their conventions. +- Adopt ecosystem trends only when they solve a concrete problem better than the existing platform. + +## FAQ + +Why DOMStack? + +: DOMStack is named after the [DOM (Document Object Model)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) and the concept of stacking technologies together to build websites. +It represents the layering of HTML, CSS, and JavaScript in a cohesive build system and its emphasis of using what we have rather than inventing brand new ideas or concepts. +Also since I had to replace a Wallace and Gromit reference, it could maybe also double as a [cheeky](https://youtu.be/tiJ4ffGZ7cM?t=77) homage to Node's former legend `substack`. + +How does `domstack` relate to [`top-bun`](https://www.npmjs.com/package/top-bun)? + +: `top-bun` is the former name of `domstack` and was named after the bakery in Wallace & Gromit's [A Matter of Loaf and Death π](https://www.youtube.com/watch?v=zXBmZLmfQZ4) which my kids were watching at the time. +The project and package were renamed to DOMStack and `@domstack/static` in v11. +See the [`top-bun` to DOMStack migration guide](../migrations/v11-migration.md) when updating an older project. +The `bun` project took off +and hosed the projects chances at SEO! + +How does `domstack` relate to [`sitedown`](https://ghub.io/sitedown) + +: `top-bun` used to be called `siteup` which is sort of like "markup", which is related to "markdown", which inspired the project `sitedown` to which `domstack` is a spiritual off-shoot of. +Put a folder of web documents in your `domstack` build system, and generate a website. +`domstack` is definitely it's own thing now though! + + +Is this for real? + +: Yes! +The frontend space is crowded and brutal, and full of repeat ideas. +DOMStack started and will remain as an opensource-for-one project and my goal is to explore ideas that I haven't seen manifest in ways I would like to see elsewhere. +Usage and contribution is encouraged and welcome and appreciated of course. +I already consider the project a success for the goals I set out to achieve with it and don't plan to growth hack it at all. + +## Project status + +DOMStack is actively developed and currently available as a v12 prerelease. +Its core feature set includes: + +- Markdown, HTML, and TypeScript pages +- Layouts with colocated styles and client bundles +- Global, layout, and page-scoped variables +- Centralized global data processing +- Generated pages and templates +- Static assets and additional copy directories +- Progressive watch rebuilds with dependency tracking +- TypeScript, JavaScript, and client-bundle TSX support +- Page-scoped Web Workers and a site service worker +- The DOMStack build manifest +- A built-in development server powered by [`@domstack/sync`][domstack-sync] + +See the [GitHub roadmap](https://github.com/users/bcomnes/projects/3/) for planned work, or the [changelog](../../CHANGELOG.md) for completed changes. +Issues, ideas, and examples of sites built with DOMStack are welcome. + +[domstack-sync]: https://www.npmjs.com/package/@domstack/sync diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 00000000..fae661a4 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,78 @@ +--- +layout: docs +docsOrder: 120 +handlebars: false +--- + +# API + +Import `DomStack` from `@domstack/static` to build sites from your own Node.js scripts. +For automated tests, `testBuild()` provides a temporary output directory and a cleanup helper. + +## Table of Contents + +[[toc]] + +## Programmatic builds + +Use the named `DomStack` export for a one-shot build with an explicit source directory, destination directory, and optional build options. +With your site in `./src` and additional files to copy in `./static`, save this as `build.mjs` and run `node build.mjs` from your project directory: + +```js +/** @import { DomStackOpts } from '@domstack/static/types.js' */ +import { DomStack } from '@domstack/static' + +/** @type {DomStackOpts} */ +const options = { + copy: ['./static'], +} + +try { + const site = new DomStack('./src', './public', options) + const results = await site.build() + + for (const warning of results.warnings) { + console.warn(warning) + } + + console.log('Built site in ./public') +} catch (error) { + console.error(error) + process.exitCode = 1 +} +``` + +`new DomStack(src, dest, opts)` accepts filesystem path strings, with relative paths resolved from the current working directory, including `opts.copy` paths. +`build()` creates the destination as needed, writes the site output, and resolves with a `Results` object containing discovery data, build-step results, and warnings. +Build failures reject the promise, so the example reports the error and sets a nonzero exit code. +The `DomStackOpts` and `Results` types are available from the type-only `@domstack/static/types.js` entry. + +## Test builds + +Use the top-level `testBuild` helper to build into a temporary directory from tests without managing setup and cleanup yourself. + +```js +import { test } from 'node:test' +import assert from 'node:assert' +import { testBuild } from '@domstack/static' + +test('site output', async () => { + const build = await testBuild('./src') + + try { + const html = await build.readOutput('index.html') + assert.match(html, /Hello/) + } finally { + await build.cleanup() + } +}) +``` + +`testBuild(src, opts)` creates a temporary destination directory, runs `new DomStack(src, dest, opts).build()`, and returns `{ dest, results, readOutput, cleanup }`. +Options are passed through to `DomStack`, including `copy` paths. + +See these repository tests for complete usage: + +- [`test-build-helper/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/test-build-helper/index.test.js) tests temporary output, `readOutput()`, copied directories, and cleanup. +- [`default-layout/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/default-layout/index.test.js) uses `testBuild()` for a focused output assertion. +- [`generated-pages/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/generated-pages/index.test.js) uses it with generated pages, global data, and templates. diff --git a/docs/assets/README.md b/docs/assets/README.md new file mode 100644 index 00000000..24fb878c --- /dev/null +++ b/docs/assets/README.md @@ -0,0 +1,74 @@ +--- +layout: docs +docsOrder: 50 +handlebars: false +--- + +# Static assets + +DOMStack copies static assets and explicitly included directories into your site without bundling or rendering them. +Browser JavaScript and CSS are separate build inputs: see [Global bundles](../global-bundles/), [page assets](../pages/#page-styles), and [layout assets](../layouts/#layout-styles). +Build-tool configuration and site-wide variables are documented separately in [Settings](../settings/). + +## Table of Contents + +[[toc]] + +## Static assets + +All static assets in the `src` directory are copied 1:1 to the destination directory using [cpx2](https://github.com/bcomnes/cpx2). +Files ending in `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.css`, `.html`, or `.md` are reserved for DOMStack processing and are not copied as static assets. + +### `--copy` directories + +You can specify directories to copy into your `dest` directory using the `--copy` flag. +Everything in those directories will be copied as-is into the destination, including js, css, html and markdown, preserving the internal directory structure. + +> [!NOTE] +> `--copy` intentionally accepts directories, not individual files. +Place a file in a directory whose structure encodes its desired destination path. +To copy multiple directories, repeat the flag: `domstack --copy oldsite --copy archived-docs`. + +> [!WARNING] +> DOMStack does not detect conflicts between copied directories and other build output. +If multiple inputs produce the same destination path, the result is undefined. + +Copy folders must live **outside** of the `dest` directory. +Copy directories can be in the src directory allowing for nested builds. +In this case they are added to the ignore glob and ignored by the rest of `domstack`. + +> [!NOTE] +> When using the programmatic `DomStack` constructor, `copy` entries may be relative or absolute paths. +Relative paths are resolved from the current working directory, matching the CLI `--copy` behavior, before being stored in `domstack.opts.copy` and passed to the copy build step. +> +> ```typescript +> const site = new DomStack('src', 'public', { +> copy: ['./legacy-site', '/srv/shared-docs'], +> }) +> ``` + +The intention of this feature is to include legacy or archived site content without asking DOMStack to process or modify it. +In general, static content should live in your primary `src` directory, but keeping older content in a separate, unprocessed directory can make it easier to merge into the final build. + +For example: + +``` +src/... +oldsite/ +βββ client.js +βββ hello.html +βββ styles/ + βββ globals.css +``` + +After build: + +``` +src/... +oldsite/... +public/ +βββ client.js +βββ hello.html +βββ styles/ + βββ globals.css +``` diff --git a/docs/cli/README.md b/docs/cli/README.md new file mode 100644 index 00000000..6d785e85 --- /dev/null +++ b/docs/cli/README.md @@ -0,0 +1,78 @@ +--- +layout: docs +docsOrder: 10 +handlebars: false +--- + +# CLI + +Use `domstack` (or its shorter alias, `dom`) to build a site, watch for changes, or preview production output. +The options below control source and destination directories, asset copying, and the development server. + +## Table of Contents + +[[toc]] + +## Usage + +```console +$ domstack --help +Usage: domstack [options] + + Example: domstack --src website --dest public + + --src, -s path to source directory (default: "src") + --dest, -d path to build destination directory (default: "public") + --ignore, -i comma separated gitignore style ignore string + --drafts Build draft pages with the `.draft.{md,js,ts,html}` page suffix. + --noEsbuildMeta skip writing the esbuild metafile to disk + --domstackManifest write the domstack manifest to disk + --eject, -e eject the DOMStack default layout, style and client into the src flag directory + --watch, -w build, watch and serve the site build + --watch-only watch and build the src folder without serving + --verbose show debug logs, including the build tree and individual copy operations + --serve build once and serve the destination directory without watching + --port port for --serve (default: 3000) + --copy path to directories to copy into dist; can be used multiple times + --help, -h show help + --version, -v show version information +domstack (v12.0.0) +``` + +`domstack` builds a `src` directory into a `dest` directory (default: `public`). + +Normal output summarizes builds, static asset startup, and server URLs. +Use `--verbose` to include the build tree and individual copy operations. +Build failures retain their full diagnostics at either verbosity level. + +- Running `domstack` will result in a `build` by default. +- Running `domstack --watch` or `domstack -w` will build the site and start an auto-reloading development web-server that watches for changes (provided by [`@domstack/sync`][domstack-sync]). + +- Running `domstack --eject` or `domstack -e` will extract the default layout, global styles, and client-side JavaScript into your source directory and add the necessary dependencies to your package.json. + +`domstack` is a devtool. +It's primarily a unix `bin` written for the [Node.js](https://nodejs.org) runtime that is intended to be installed from `npm` as a `devDependency` inside a `package.json` committed to a `git` repository. +It can be used outside of this context, but it works best within it. + +## Ejecting the defaults + +The `--eject` (or `-e`) flag extracts DOMStack's default layout, global CSS, and client-side JavaScript into your source directory. +This allows you to fully customize these files while maintaining the same functionality. + +When you run `domstack --eject`, it will: + +1. + Create a default root layout file at `layouts/root.layout.js` (or `.mjs` depending on your package.json type) +2. + Create a default global CSS file at `globals/global.css` +3. + Create a default client-side JavaScript file at `globals/global.client.js` +4. + Add the necessary dependencies to your package.json: + - mine.css + - fragtml + - highlight.js + +It is recommended to eject early in your project so that you can customize the root layout as you see fit, and decouple yourself from potential unwanted changes in the default layout as new versions of DOMStack are released. + +[domstack-sync]: https://www.npmjs.com/package/@domstack/sync diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md new file mode 100644 index 00000000..edde149c --- /dev/null +++ b/docs/cookbook/README.md @@ -0,0 +1,15 @@ +--- +layout: docs +docsOrder: 130 +handlebars: false +--- + +# Recipes + +These recipes combine DOMStack features to solve common site-building tasks. +Use them as starting points for nested layouts, feeds, archive pages, and redirects. + +- [Compose nested layouts](./nested-layouts/) with `parentLayout` declarations, focused data subscriptions, and inherited assets. +- [Generate RSS and JSON feeds](./feeds/) from the ten most recent blog pages. +- [Generate yearly blog index pages](./yearly-blog-indexes/) from date-sorted source pages. +- [Generate redirect pages from page metadata](./redirect-pages/) to preserve old URLs. diff --git a/docs/cookbook/feeds/README.md b/docs/cookbook/feeds/README.md new file mode 100644 index 00000000..463b8f97 --- /dev/null +++ b/docs/cookbook/feeds/README.md @@ -0,0 +1,129 @@ +--- +layout: docs +docsOrder: 132 +docsParent: /docs/cookbook/ +handlebars: false +--- + +# Generate RSS and JSON feeds + +[All recipes](../) + +Use `global.data.ts` to inspect and render source pages, then let a feed template subscribe to the prepared records. + +The following example generates an [RSS](https://www.rssboard.org) and [JSON Feed](https://www.jsonfeed.org) from the 10 most recent date-sorted pages using the `blog` layout and the AsyncIterator template type. +It uses [`renderInnerPage()`](../../data/#rendering-page-content) while global data is computed, so the template never receives the page graph. +See the [blog example's `global.data.ts`](https://github.com/bcomnes/domstack/blob/master/examples/blog/src/global.data.ts) and [`feeds.template.ts`](https://github.com/bcomnes/domstack/blob/master/examples/blog/src/feeds.template.ts) for a working implementation. + +```typescript +// src/global.data.ts +import type { AsyncGlobalDataFunction } from '@domstack/static/types.js' + +export interface FeedItem { + datePublished: string + title: string + urlPath: string + contentHtml: string +} + +export interface GlobalData { + feedItems: FeedItem[] +} + +export type FeedsTemplateData = PickHello from the post.
' +``` + +DOMStack renders `root(article(page()))`. +A root layout omits `parentLayout`; child layouts can name any discovered layout, including the bundled `root`. +Names are the same filename-derived names used by `vars.layout`, not import paths. +Missing parents, invalid parent exports, and cycles fail the build with the offending layout or chain. + +All renderers receive the same resolved vars, page metadata, worker URLs, and asset lists. +Vars merge from outermost to innermost layout, followed by page vars and builder/frontmatter vars. +Layout `vars.layout` does not select a parent; only the named `parentLayout` export establishes nesting. +Async layouts are awaited at every step, and intermediate values pass through unchanged until the final result is serialized. +Each parent must accept the kind of children its immediate child returns. + +## Data subscriptions in nested layouts + +Each layout declares only the data it reads. +Keep focused consumer types beside their producer in `global.data.ts`: + +```typescript +// global.data.ts +export type RootLayoutData = { navigation: { title: string, url: string }[] } +export type ArticleLayoutData = { recentPosts: { title: string, url: string }[] } +export type GlobalData = RootLayoutData & ArticleLayoutData +``` + +```typescript +// root.layout.ts +import type { DataDeps } from '@domstack/static/types.js' +import type { RootLayoutData } from './global.data.ts' + +export const vars = { + dataDeps: ['navigation'] satisfies DataDepsRedirecting to ${vars.redirectTo}
+ +`) +} +``` + +`redirectFrom` contains old same-origin public URL paths. +`redirectOutputName()` converts directory URLs such as `/2020/old-slug/` to `2020/old-slug/index.html`. +DOMStack's generated-output validation still rejects escaping paths such as `..`. +The redirect target comes from the current page's normalized `pageInfo.url`, so moving the page again only requires retaining its previous URLs in that page's metadata. +`fragtml` escapes interpolated values by default, including attribute values and link text. + +**SEO note:** Meta-refresh is a client-side redirect. +Search engines may not treat it as a permanent 301 redirect. +For static hosting platforms that support server-side redirects, you can instead generate a `_redirects` file (Netlify, Cloudflare Pages) or `vercel.json` (Vercel) using the object template type: + +```typescript +// src/redirects-netlify.txt.template.ts +// Generates a _redirects file for Netlify / Cloudflare Pages. + +export const dataDeps = ['redirects'] + +export default function ({ data }) { + return { + outputName: '_redirects', + content: data.redirects.map(({ from, to }) => `${from} ${to} 301`).join('\n'), + } +} +``` + +Both approaches can coexist and consume the same `global.data.ts` redirect collection. +Copying a directory that contains a hand-crafted `_redirects` file via `--copy` is also an option when you prefer to manage redirects outside the build. diff --git a/docs/cookbook/yearly-blog-indexes/README.md b/docs/cookbook/yearly-blog-indexes/README.md new file mode 100644 index 00000000..40ad5e60 --- /dev/null +++ b/docs/cookbook/yearly-blog-indexes/README.md @@ -0,0 +1,115 @@ +--- +layout: docs +docsOrder: 133 +docsParent: /docs/cookbook/ +handlebars: false +--- + +# Generate yearly blog index pages + +[All recipes](../) + +Global data centralizes collection and grouping once, then generated pages turn those records into pages. +See the working [blog example directory](https://github.com/bcomnes/domstack/tree/master/examples/blog/), [`global.data.ts`](https://github.com/bcomnes/domstack/blob/master/examples/blog/src/global.data.ts), [`blog-indexes.pages.ts`](https://github.com/bcomnes/domstack/blob/master/examples/blog/src/blog-indexes.pages.ts), and [`year-index.layout.ts`](https://github.com/bcomnes/domstack/blob/master/examples/blog/src/layouts/year-index.layout.ts). + +First, collect source-backed pages whose layout is `post`, validate and normalize their publish dates, sort them newest-first, and group them into yearly `blogIndexes`: + +```typescript +// src/global.data.ts +import type { + AsyncGlobalDataFunction, + GlobalDataFunctionParams, +} from '@domstack/static/types.js' + +export interface BlogPost { + path: string + title: string + publishDate: string +} + +export interface BlogIndex { + year: number + posts: BlogPost[] +} + +export interface GlobalData { + blogIndexes: BlogIndex[] +} + +export type BlogIndexesPagesData = PickAbout this site
', +} +``` + +#### Page definition array + +Export an array when the module always creates a fixed set of pages: + +```ts +// src/legal.pages.ts +export default [ + { + outputName: 'terms/index.html', + vars: { layout: 'legal', title: 'Terms' }, + children: 'Terms of service', + }, + { + outputName: 'privacy/index.html', + vars: { layout: 'legal', title: 'Privacy' }, + children: 'Privacy policy', + }, +] +``` + +#### Synchronous factory + +Export a function when definitions depend on declared global data or shared variables: + +```ts +// src/tag-indexes.pages.ts +export const dataDeps = ['tagIndex'] + +export default function tagIndexes ({ data }) { + return Object.entries(data.tagIndex).map(([tag, posts]) => ({ + outputName: `tags/${tag}/index.html`, + vars: { layout: 'tag-index', title: `Posts tagged ${tag}`, posts }, + })) +} +``` + +For a complete two-stage factory example, see [Generate yearly blog index pages](../cookbook/yearly-blog-indexes/). + +#### Asynchronous factory + +Export an async function when creating definitions requires asynchronous work: + +```ts +// src/team.pages.ts +import { readFile } from 'node:fs/promises' + +export default async function teamPages () { + const members = JSON.parse( + await readFile(new URL('./data/team.json', import.meta.url), 'utf8') + ) + + return members.map(member => ({ + outputName: `team/${member.slug}/index.html`, + vars: { layout: 'profile', title: member.name, member }, + })) +} +``` + +#### Async iterable + +Export an async generator when pages should be yielded incrementally: + +```ts +// src/archive.pages.ts +export const dataDeps = ['blogYears'] + +export default async function * archivePages ({ data }) { + for (const year of data.blogYears) { + yield { + outputName: `blog/${year}/index.html`, + vars: { layout: 'archive', year }, + } + } +} +``` + +### Generated-pages factory parameters + +Functions receive one object with: + +| Parameter | Contents | +|---|---| +| `vars` | Default and global vars. | +| `data` | Only the top-level values named by the module's `dataDeps` export. | +| `pagesFile` | Information about the current file. `name` is the filename without its `.pages.*` suffix, `path` is its source-relative directory, and `pagesFile` contains the underlying file information. | + +Factories do not receive raw source or generated `PageData` collections. +Put page-collection logic in [`global.data.ts`](../data/#global-data), return a focused serializable value, and subscribe to its key from the factory. +This keeps factories downstream of source discovery without exposing generation order or creating page-generation cycles. + +### Generated page definitions + +| Field | Behavior | +|---|---| +| `outputName` | Output path relative to the pages file's directory. It must name a file, must not be absolute or contain `..` segments, and cannot end in a path separator. Defaults to `+flowchart TD + accTitle: One-shot build + accDescr: Discover inputs, run three asset tasks in parallel, build pages, then finalize the manifest and service worker before returning results. + IDENTIFY["`**identifyPages()** +Find pages, layouts, templates +Find globals and settings`"] + PREPARE["`**Prepare destination** +Resolve manifest options +Start parallel asset tasks`"] + ESBUILD["`**buildEsbuild()** +Bundle browser JS and CSS +Record outputs`"] + STATIC["`**buildStatic()** +Copy static files if enabled +Record outputs`"] + COPY["`**buildCopy()** +Copy extra directories +Record outputs`"] + PAGES["`**buildPages()** +Start a fresh page worker +Render pages and templates +Apply layouts; record outputs`"] + FINALIZE["`**Finalize build** +Reconcile manifest if enabled +Run hooks; build service worker`"] + RESULTS["`**Return results** +Discovery and build reports +Manifest and warnings +Write manifest JSON if requested`"] + IDENTIFY --> PREPARE + PREPARE --> ESBUILD & STATIC & COPY + ESBUILD & STATIC & COPY --> PAGES + PAGES --> FINALIZE --> RESULTS ++ +The build process follows these key steps: + +1. **Page identification** - Scans the source directory to identify all pages, layouts, templates, and global assets +2. **Destination preparation** - Ensures the destination directory is ready for the build output +3. **Parallel asset processing** - Three operations run concurrently and record their outputs: + - JavaScript and CSS bundling via esbuild + - Static file copying (when enabled) + - Additional directory copying (from `--copy` options) +4. **Page building** - Initializes source-backed pages, derives global data, generates pages, and renders pages and templates with their declared data subscriptions +5. **Manifest reconciliation** - When enabled, normalizes recorded outputs, hashes file contents, filters entries, computes a stable manifest version, and runs manifest hooks +6. **Service-worker building** - Bundles the site service worker using any defines returned by manifest hooks; this output is not included in the already reconciled manifest +7. **Return results** - Writes manifest JSON only when requested and returns the build results + +This architecture allows for efficient parallel processing of independent tasks while maintaining the correct build order dependencies. +The diagrams show successful execution; discovery and build errors stop later phases. + +### buildPages() detail + +Each `buildPages()` call starts a fresh worker so server-side modules can be reloaded between watch builds. +Within that worker, source-backed pages are initialized before global data is computed. +Generated pages are downstream consumers of that data, not inputs to its producer. +The three source-page lanes show the work performed for each page type, not three separate concurrency pools. + +
+flowchart TD + accTitle: Page worker stages + accDescr: Initialize Markdown, HTML, and JS or TS source pages in parallel. Derive global data from those pages, generate additional pages, then render pages and templates in parallel. + RESOLVE["`**Resolve once** +Defaults and global vars +Layouts and parent chains`"] + INIT["`**Parallel source-page init** +Concurrency: min(CPUs, 24)`"] + subgraph MD["Markdown page task"] + direction TB + MD_VARS["Resolve page.vars"] + MD_READ["`**mdBuilder()** +Read Markdown +Title and frontmatter`"] + MD_VARS --> MD_READ + end + subgraph HTML["HTML page task"] + direction TB + HTML_VARS["Resolve page.vars"] + HTML_READ["`**htmlBuilder()** +Read HTML source`"] + HTML_VARS --> HTML_READ + end + subgraph JS["JS / TS page task"] + direction TB + JS_VARS["Resolve page.vars"] + JS_READ["`**jsBuilder()** +Import page module +Read exported vars`"] + JS_VARS --> JS_READ + end + BIND["`**Finish each page init** +Merge vars and bind layouts +Collect assets and dataDeps`"] + DATA["`**global.data** +Receive initialized source PageData[] +Derive shared data`"] + SUBSCRIBE["`**Select declared data** +Project dataDeps for consumers +In watch: expand invalidated filters`"] + GENERATE["`**Run pages-file factories** +Consume declared data +Define generated pages`"] + GENERATED_INIT["`**Initialize generated pages** +Resolve vars, layouts, and assets +Bind declared data`"] + subgraph RENDER["Parallel rendering Β· shared concurrency budget"] + direction TB + PAGE_RENDER["`**pageWriter()** +Render source and generated pages +Wrap layouts inner to outer +Write outputs`"] + TEMPLATE_RENDER["`**templateBuilder()** +Render selected templates +Use declared data +Write outputs`"] + end + REPORT["`**Return page-build results** +Outputs, errors, and layout reports +Subscriptions in watch mode`"] + RESOLVE --> INIT + INIT --> MD & HTML & JS + MD & HTML & JS --> BIND + BIND --> DATA --> SUBSCRIBE --> GENERATE --> GENERATED_INIT + GENERATED_INIT --> RENDER --> REPORT ++ +Selected `*.pages.*` factories produce definitions that go through the same page initialization as source-backed pages. +Each page, layout, template, and pages-file factory receives only the global-data keys it declares through `dataDeps`. +Layout subscriptions contribute to page invalidation, but each layout still receives its own data projection while rendering. +Page initialization uses a concurrency limit of `min(CPUs, 24)`. +The final page and template rendering queues run in parallel, splitting that concurrency budget between them. + +Variable Resolution Layers, from lowest to highest precedence: +- **Domstack defaults** - Internal defaults such as the default `layout: 'root'`. +- **Global vars** - Site-wide variables from `global.vars.js` (resolved once). +- **Layout vars** - Optional `export const vars` from the resolved layout chain, merged outermost to innermost. +- **Page-specific vars** vary by type: + - **MD pages**: `page.vars.js` plus builder vars from frontmatter. + - **HTML pages**: `page.vars.js`. + - **JS pages**: exported `vars` plus `page.vars.js`. + +Global data is not a variable-resolution layer. +It is resolved separately and projected into each consumer's `data` argument according to `dataDeps`. + +## Watch mode + +Running `domstack --watch` or `domstack -w` performs an initial build, watches the source inputs, and serves `dest` with live reload. +Use `domstack --watch-only` when another process serves the output. + +Watch mode coordinates three independent watchers: + +- **esbuild** uses `context.watch()` for global, layout, and page client bundles, styles, page-scoped Web Workers, and the site service worker. +- **chokidar** watches page, layout, template, generated-pages, variable, and settings modules. + DOMStack uses the changed file and its dependency maps to choose a rebuild scope. +- **cpx2** watches static assets under `src` and directories supplied with `--copy`, copying or removing their destination files directly. + +Chokidar events pass through a pure planner before any rebuild executes. +The planner reads an explicit snapshot of discovery, dependency maps, and the previous page-build outcome; it does not perform I/O or mutate that state. +`DomStack` owns the watch session, serializes events, executes plans, and releases its watchers, esbuild context, and server on shutdown. + +
+flowchart TD
+ accTitle: Watch planning and execution
+ accDescr: Serialized Chokidar events produce a pure watch plan. DOMStack executes it, replans after bundle discovery when needed, and retains the last successful routing after page-build errors.
+ EVENT["Chokidar event"] --> QUEUE["Serialize in the watch session"]
+ subgraph PLANNING["Pure planning Β· no I/O"]
+ direction TB
+ CLASSIFY["Shared file conventions"]
+ PLAN["`**planWatchEvent()**
+Inspect watch snapshot`"]
+ CLASSIFY --> PLAN
+ end
+ QUEUE --> PLANNING
+ PLANNING --> EXECUTE{"Execute plan"}
+ EXECUTE -->|Skip| SKIP["No page rebuild"]
+ EXECUTE -->|Full| FULL["`Rediscover inputs
+Restart esbuild`"]
+ EXECUTE -->|Restart| RESTART["`Rediscover bundle entries
+Restart esbuild`"]
+ RESTART --> BUNDLE["`**planBundleChange()**
+Use refreshed discovery
+Keep successful layout routing`"]
+ BUNDLE --> EXECUTE
+ EXECUTE -->|Pages| PAGES["`**buildPages()**
+Full or filtered page phase`"]
+ FULL --> PAGES
+ PAGES --> SUCCESS{"Page build succeeded?"}
+ SUCCESS -->|Yes| SAVE["`Reconcile owned outputs
+Refresh routing and subscriptions`"]
+ SUCCESS -->|No| RETAIN["`Keep successful ownership and routing
+Require a full page retry`"]
+
+
+Bundle replanning returns only a page plan or a skip; it does not restart esbuild again.
+After a page-build failure, the next page-producing plan retries the complete page phase rather than trusting incremental filters.
+Manifest-settings changes and service-worker entry additions or removals retain their intentional page-phase skips.
+The one-shot manifest pipeline is not part of watch execution.
+
+> [!NOTE]
+> The filenames below use `.ts` by default.
+You can also use `.js`, and TypeScript client bundles can use `.tsx`.
+See [Supported file types](../../docs/typescript/#supported-file-types) for all available extensions.
+
+DOMStack uses these rebuild scopes:
+
+- **esbuild only**: esbuild updates an existing browser entry without rendering HTML.
+- **Targeted page/template rebuild**: DOMStack renders only the affected source-backed pages or templates.
+- **Targeted generated-pages rebuild**: DOMStack renders and reconciles only the outputs owned by affected `*.pages.ts` files.
+- **Full page/template rebuild**: DOMStack renders every source-backed and generated page and every template without restarting esbuild.
+- **Full rebuild**: DOMStack rediscovers the source tree, restarts esbuild, renders all pages and templates, and refreshes its dependency maps.
+
+Like templates, generated-pages modules rebuild when their own source or imported dependencies change.
+When a targeted build recomputes global data, DOMStack compares top-level values with the previous successful build and adds only subscribers of changed keys to the rebuild set.
+
+### What triggers what
+
+| Change | Rebuild scope |
+|---|---|
+| Existing `page.ts`, `page.html`, `page.md`, or adjacent `page.vars.ts` | That page, plus subscribers of any changed global-data keys |
+| A module imported by a TypeScript page or `page.vars.ts` | Pages that depend on it, plus subscribers of any changed global-data keys |
+| Existing `*.layout.ts` or a module it imports | Source-backed pages and generated-page owners using the affected layout |
+| Existing `*.template.ts` or a module it imports | Affected templates |
+| Existing `*.pages.ts` | Generated outputs owned by that file, then refresh dependency maps |
+| A module imported by `*.pages.ts` | Generated outputs owned by the importing files, then refresh dependency maps |
+| `markdown-it.settings.ts` | All source-backed Markdown pages, plus subscribers of any changed global-data keys |
+| `global.data.ts` | Consumers subscribed to top-level keys whose values changed |
+| `global.vars.ts` or `esbuild.settings.ts` | Full rebuild |
+| `domstack-manifest.settings.ts` | No rebuild. The manifest pipeline is disabled in watch mode |
+| Existing client, style, Web Worker, or service-worker entry | esbuild only, unless the same module also has server-side consumers |
+| Static asset under `src` or a file under a `--copy` directory | cpx2 copies or removes the output directly |
+
+Adding or removing a file changes the set of discovered build inputs:
+
+| Added or removed file | Rebuild scope |
+|---|---|
+| Site `service-worker.ts` | Restart esbuild. No page rebuild |
+| `global.client.ts` or `global.css` | Restart esbuild and rebuild all pages |
+| Layout client or style | Restart esbuild and rebuild source-backed pages and generated-page owners using that layout |
+| Page client, style, or Web Worker | Restart esbuild and rebuild that page |
+| Any other page, layout, template, generated-pages, variable, or settings file | Full rebuild |
+
+When a full page/template rebuild or targeted generated-pages rebuild no longer claims an output from the previous successful build, DOMStack removes that obsolete page or template output from `dest` without touching outputs owned by unaffected files.
+
+### Dependency tracking
+
+DOMStack uses [`@11ty/dependency-tree-typescript`](https://github.com/11ty/dependency-tree-typescript) to statically analyze ESM imports.
+It maintains maps for:
+
+- Layout dependencies, source-backed pages using each layout, and generated-page owner layout membership
+- TypeScript pages and adjacent page-variable dependencies
+- Template dependencies
+- Generated-pages module dependencies
+- Current esbuild entry points
+
+The maps are created after the initial build and refreshed after successful page builds and structural rediscovery.
+Layout routing and generated-output ownership use reports from successful page builds.
+Dependency analysis is best-effort.
+When DOMStack cannot safely determine a targeted scope, it falls back to a broader rebuild or skips an unrelated changed module.
+
+esbuild tracks browser-entry dependencies independently.
+Changing a module imported only by `client.ts` rebundles that entry without rendering page HTML.
+When a module has both browser and server-side consumers, the planner unions the server-side consumers rather than skipping the page phase.
+
+### Stable entry filenames
+
+Watch mode uses stable filenames for esbuild entry outputs:
+
+```text
+[dir]/[name]
+```
+
+Production builds use content-hashed entry filenames:
+
+```text
+[dir]/[name]-[hash]
+```
+
+Shared chunks remain content-hashed in both modes:
+
+```text
+chunks/[ext]/[name]-[hash]
+```
+
+Page HTML points to stable entry files during watch mode. esbuild can update an entry and its chunk imports without requiring DOMStack to render the page again.
+
+### Manifest behavior
+
+Watch mode builds and rebundles the site service worker, but it does not finalize, return, or write the [DOMStack manifest](../../docs/workers/#domstack-manifest).
+Changes to `domstack-manifest.settings.ts` therefore do not trigger a watch rebuild.
+
+Use `domstack --serve` when testing manifest-driven cache behavior.
+It runs a one-shot build and serves the result without watch-mode filenames or live-reload HTML injection.
+Add `--domstackManifest` only when the service worker or test needs the public `domstack-manifest.json` file.
+
+### Build serialization
+
+Chokidar events are serialized through a promise chain.
+Each page rebuild or esbuild restart completes before the next queued filesystem event is processed, preventing overlapping DOMStack rebuilds during rapid saves.
diff --git a/docs/implementation/client.ts b/docs/implementation/client.ts
new file mode 100644
index 00000000..80b35627
--- /dev/null
+++ b/docs/implementation/client.ts
@@ -0,0 +1,24 @@
+/// This is just some html.
+My favorite cookie: ${vars.favoriteCookie}
+I love ${favoriteCake}!!
+${code}${code}`
+ for (const children of [contents, html`Redirecting to ${vars.redirectTo}
- -