This is just some html.
-My favorite cookie: ${vars.favoriteCookie}
-I love ${favoriteCake}!!
-About this site
', -} -``` +advanced-type-parameters -#### 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', - }, -] -``` +advanced -#### Synchronous factory +custom-layout-renderers -Export a function when definitions depend on declared global data or shared variables: +web-workers -```ts -// src/tag-indexes.pages.ts -export const dataDeps = ['tagIndex'] +service-workers -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 }, - })) -} -``` +registration-and-web-app-manifests -For a complete two-stage factory example, see [Generate yearly blog index pages](#generate-yearly-blog-index-pages). +domstack-manifest -#### Asynchronous factory +enable-the-manifest -Export an async function when creating definitions requires asynchronous work: +configure-entries-and-policy -```ts -// src/team.pages.ts -import { readFile } from 'node:fs/promises' +manifest-built-hooks -export default async function teamPages () { - const members = JSON.parse( - await readFile(new URL('./data/team.json', import.meta.url), 'utf8') - ) +service-worker-integration - return members.map(member => ({ - outputName: `team/${member.slug}/index.html`, - vars: { layout: 'profile', title: member.name, member }, - })) -} -``` +programmatic-configuration -#### Async iterable +programmatic-test-builds -Export an async generator when pages should be yielded incrementally: +cookbook -```ts -// src/archive.pages.ts -export const dataDeps = ['blogYears'] +compose-nested-layouts -export default async function * archivePages ({ data }) { - for (const year of data.blogYears) { - yield { - outputName: `blog/${year}/index.html`, - vars: { layout: 'archive', year }, - } - } -} -``` +layout-composition-pitfalls -### Generated-pages factory parameters +data-subscriptions-in-nested-layouts -Functions receive one object with: +manual-composition -| 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. | +nested-layout-client-bundles-and-styles -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. +generate-rss-and-json-feeds -### Generated page definitions +generate-yearly-blog-index-pages -| 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 - -[MIT](LICENSE) +project-status -[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,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 +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](../../docs/cookbook/#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. + +[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 diff --git a/docs/example-projects/README.md b/docs/example-projects/README.md new file mode 100644 index 0000000..c3a1809 --- /dev/null +++ b/docs/example-projects/README.md @@ -0,0 +1,62 @@ +--- +layout: docs +handlebars: false +--- + +# Example projects + +## Table of Contents + +[[toc]] + +## Examples + +A collection of examples can be found in the [`./examples`](https://github.com/bcomnes/domstack/tree/master/examples) folder: + +- [`basic`](https://github.com/bcomnes/domstack/tree/master/examples/basic) β A broad tour of Markdown, HTML, and TypeScript pages, nested pages and layouts, variables, styles, client bundles, and static assets. +- [`blog`](https://github.com/bcomnes/domstack/tree/master/examples/blog) β A blog with derived global data, generated archive pages, redirects, nested layouts, and feed templates. +- [`css-modules`](https://github.com/bcomnes/domstack/tree/master/examples/css-modules) β Using CSS Modules from page code alongside global and page styles. +- [`default-layout`](https://github.com/bcomnes/domstack/tree/master/examples/default-layout) β Building a Markdown site with DOMStack's built-in default layout and no custom layout. +- [`esbuild-settings`](https://github.com/bcomnes/domstack/tree/master/examples/esbuild-settings) β Customizing the browser build through `esbuild.settings`. +- [`markdown-settings`](https://github.com/bcomnes/domstack/tree/master/examples/markdown-settings) β Customizing Markdown rendering with `markdown-it.settings` and Markdown-it plugins. +- [`nested-dest`](https://github.com/bcomnes/domstack/tree/master/examples/nested-dest) β Using the project root as `src` while writing the built site to a nested `public` directory. +- [`preact-isomorphic`](https://github.com/bcomnes/domstack/tree/master/examples/preact-isomorphic) β Rendering with Preact on the server and mounting page-scoped Preact and JSX in the browser. +- [`react`](https://github.com/bcomnes/domstack/tree/master/examples/react) β Configuring React and TypeScript for a page-scoped TSX client. +- [`static-mpa-offline`](https://github.com/bcomnes/domstack/tree/master/examples/static-mpa-offline) β A static multi-page app with DOMStack manifests, an offline fallback, precaching, and custom service-worker caching policies. +- [`static-mpa-workbox-offline`](https://github.com/bcomnes/domstack/tree/master/examples/static-mpa-workbox-offline) β The offline static MPA pattern implemented with Workbox routing, strategies, and precaching. +- [`string-layouts`](https://github.com/bcomnes/domstack/tree/master/examples/string-layouts) β Writing layouts that return plain HTML strings instead of using the default renderer. +- [`tailwind`](https://github.com/bcomnes/domstack/tree/master/examples/tailwind) β Integrating Tailwind CSS through an esbuild plugin. +- [`type-stripping`](https://github.com/bcomnes/domstack/tree/master/examples/type-stripping) β Using Node.js type stripping for TypeScript pages and layouts, plus a page-scoped TSX client. +- [`uhtml-isomorphic`](https://github.com/bcomnes/domstack/tree/master/examples/uhtml-isomorphic) β Rendering with `uhtml-isomorphic` on the server and mounting or hydrating UI in the browser. +- [`worker-example`](https://github.com/bcomnes/domstack/tree/master/examples/worker-example) β Bundling and communicating with page-scoped JavaScript and TypeScript Web Workers. + +To run an example: + +```bash +$ git clone git@github.com:bcomnes/domstack.git +$ cd domstack +# install the root package and all example workspaces +$ npm i +# build one example workspace +$ npm --workspace @domstack/basic-example run build +``` + +### External examples + +Here are some additional external examples of larger domstack projects. +If you have a project that uses domstack and could act as a nice example, please PR it to the list! + +- [Blog Example](https://github.com/bcomnes/bret.io/) - A personal blog written with DOMStack +- [Isomorphic Static/Client App](https://github.com/hifiwi-fi/breadcrum.net/tree/master/packages/web/client) - Pages build from client templates and hydrate on load. +- [Zero-Conf Markdown Docs](https://github.com/bcomnes/deploy-to-neocities/blob/70b264bcb37fca5b21e45d6cba9265f97f6bfa6f/package.json#L38) - A npm package with markdown docs, transformed into a website without any any configuration + +(Did you make a cool DOMStack website that is open source? +PR it to the list!) + +[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 diff --git a/docs/implementation/README.md b/docs/implementation/README.md new file mode 100644 index 0000000..8929e44 --- /dev/null +++ b/docs/implementation/README.md @@ -0,0 +1,298 @@ +--- +layout: docs +handlebars: false +--- + +# Build internals + +## Table of Contents + +[[toc]] + +## 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](../../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 | +| 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](../../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. + +[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 diff --git a/docs/pages/README.md b/docs/pages/README.md new file mode 100644 index 0000000..1974639 --- /dev/null +++ b/docs/pages/README.md @@ -0,0 +1,678 @@ +--- +layout: docs +handlebars: false +--- + +# Page authoring reference + +## Table of Contents + +[[toc]] + +## Pages + +Pages are named directories inside `src` with **one of** the following page files: + +- `md` pages are [CommonMark](https://commonmark.org) markdown pages, with an optional [YAML](https://yaml.org) front-matter block. +- `html` pages are an inner [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) fragment that get inserted into the page layout. +- `ts` pages are [TypeScript](https://developer.mozilla.org/en-US/docs/Glossary/TypeScript) files that export a default function that resolves into an inner HTML fragment inserted into the page layout. + +> [!NOTE] +> A **source-backed page** is discovered directly from a page file in `src`, rather than created by a `*.pages.ts` module. +Source-backed pages exist before `global.data.ts` and [Generated Pages](../../docs/content/#generated-pages) run. + +Variables are available in all pages. +`md` and `html` pages support variable access via [handlebars][hb] template blocks. +`ts` pages receive variables as part of the argument passed to them. +See the [Variables](../../docs/pages/#variables) section for more info. + +Pages can define a special variable called [`layout`](../../docs/pages/#layouts) that determines which layout the page is rendered into. + +Because pages are just directories, they nest and structure naturally as a filesystem router. +Directories in the `src` folder that lack one of these special page files can exist alongside page directories and can be used to store co-located code or static assets without conflict. + +### `md` pages + +A `md` page looks like this on the filesystem: + +```bash +src/page-name/page.md +# or +src/page-name/README.md +# or +src/page-name/loose-md.md +``` + +- `md` pages have three types: a `page.md`, a `README.md`, or a loose `whatever-name-you-want.md` file. +- `page.md` and `README.md` files transform to an `index.html` at the same path. + When both exist in the same directory, `page.md` takes precedence over `README.md`. + `whatever-name-you-want.md` loose markdown files transform into `whatever-name-you-want.html` files at the same path in the `dest` directory. +- `md` pages can have [YAML](https://yaml.org/) [frontmatter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter), with variables that are accessible to the page layout and handlebars template blocks when building. +- You can include HTML in markdown files, so long as you adhere to the allowable markdown syntax around html tags. +- `md` pages support [handlebars][hb] template placeholders. +- You can disable `md` page [handlebars][hb] processing by setting the `handlebars` variable to `false`. +- `md` pages support many [github flavored markdown features](https://github.com/bcomnes/domstack/blob/master/lib/build-pages/page-builders/md/get-md.js#L25-L36). + +An example of a `md` page: + +```markdown +--- +title: A title for a markdown page +favoriteColor: 'Blue' +--- + +Just writing about web development. + +## Favorite colors + +My favorite color is {{ vars.favoriteColor }}. +``` + +### `html` pages + +A `html` page looks like this: + +```bash +src/page-name/page.html +``` + +- `html` pages are named `page.html` inside an associated page folder. +- `html` pages are the simplest page type in `domstack`. + They let you build with raw html for when you don't want that page to have access to markdown features. + Some pages are better off with just raw `html`, and the rules with building `html` in a real `html` file are much more flexible than inside of a `md` file. +- `html` page variables can only be set in a `page.vars.ts` file inside the page directory. +- `html` pages support [handlebars][hb] template placeholders. +- You can disable `html` page [handlebars][hb] processing by setting the `handlebars` variable to `false`. + +An example `html` page: + +```html +This is just some html.
+My favorite cookie: ${vars.favoriteCookie}
+I love ${favoriteCake}!!
+