Add build output manifest for static caching by bcomnes · Pull Request #262 · bcomnes/domstack

bcomnes · 2026-06-15T04:39:14Z

Summary

This adds an unstable-preview domstack output manifest for static app caching and pairs it with first-class site service-worker support.

Warning

The domstack manifest, domstack-manifest.settings.*, first-class service-worker.* entries, and related browser process.env.DOMSTACK_* defines are preview APIs. Their names, option shapes, manifest schema, generated output, and runtime semantics may change outside of a major version while the API is validated with real PWA use cases. Consumers should pin @domstack/static to an exact version before relying on this contract.

The goal is to let a domstack app build a fully static client, then have its own service worker consume a normalized, revisioned list of emitted files. Domstack provides the build facts; the application still owns service-worker registration, update UX, route filtering, offline behavior, and cache policy.

What Changed

Add domstack-manifest.json, written by one-shot builds by default.
Return results.domstackManifest from programmatic builds.
Track outputs from esbuild, pages, templates, static copies, and configured copy dirs through shared report.outputs records.
Reconcile those records once at the end of the build into public manifest entries with URLs, revisions, byte sizes, kinds, and optional source/page metadata.
Add a committed JSON Schema for the manifest with a versioned unpkg $schema URL.
Derive/export public manifest types through @domstack/static/types.js / #types using json-schema-to-ts.
Add domstack-manifest.settings.{js,mjs,cjs,ts,mts,cts} for manifest filtering policy.
Add first-class site service-worker entries: one service-worker.{js,mjs,cjs,ts,mts,cts} anywhere under src builds to stable root /service-worker.js.
Add domstack-owned browser defines for service workers and client bundles.
Keep watch mode simple: service workers still rebundle in watch mode, but domstack manifests are not written or returned in watch mode.
Replace .npmignore with a package.json#files allowlist.
Add a PWA example showing app-owned registration, update UX, manifest filtering, and cache lifecycle handling.

New Preview APIs

Build Results

const results = await site.build()
console.log(results.domstackManifest)

results.domstackManifest is still returned when writing the JSON file is disabled with domstackManifest: false. Watch mode does not return a domstack manifest.

CLI Options

domstack --customDomstackManifestName custom-domstack-manifest.json
domstack --noDomstackManifest
domstack --serve

--customDomstackManifestName changes the written manifest filename from the default domstack-manifest.json. --noDomstackManifest disables writing the JSON file. --serve runs a one-shot build and then serves the output without watch mode, which is useful for testing service-worker cache lifecycle behavior with a manifest-enabled build.

Programmatic Options

const site = new DomStack('src', 'public', {
  domstackManifest: {
    filename: 'custom-domstack-manifest.json',
    exclude: ['blog/**', '**/*.map'],
  },
})

Supported shape:

type DomstackManifestOption = false | {
  write?: boolean
  filename?: string
  exclude?: string[]
}

`domstack-manifest.settings.*`

Apps can configure the generated manifest from a dedicated settings file anywhere under src:

domstack-manifest.settings.js
domstack-manifest.settings.mjs
domstack-manifest.settings.cjs
domstack-manifest.settings.ts
domstack-manifest.settings.mts
domstack-manifest.settings.cts

The default export can be an object, a sync function, or an async function returning an object:

export default {
  exclude: ['admin/**', 'blog/**', '**/*.map'],
  includeEntry (entry) {
    if (entry.kind === 'metadata') return false
    if (entry.kind === 'sourcemap') return false
    if (entry.page?.vars?.precache === false) return false
    if (entry.page?.vars?.offline === false) return false
    return true
  },
}

Filtering affects both the written domstack-manifest.json and results.domstackManifest, and it affects manifest.version because versioning is based on final cache-relevant entries.

Service Worker Support

Domstack reserves one site service-worker source filename:

service-worker.js
service-worker.mjs
service-worker.cjs
service-worker.ts
service-worker.mts
service-worker.cts

The source may live anywhere under src, but only one is allowed. Multiple matches fail with DOM_STACK_ERROR_DUPLICATE_SERVICE_WORKER.

The service worker is bundled through esbuild and emitted with a stable root output path:

/service-worker.js

Domstack does not inject registration into the default layout. Registration timing, update prompts, local-development opt-outs, poisoned-cache recovery, and offline route behavior remain application policy.

Browser Defines

Define	Value
`process.env.DOMSTACK_MANIFEST_URL`	Public URL of the written domstack manifest, usually `/domstack-manifest.json`
`process.env.DOMSTACK_MANIFEST_ENABLED`	`"true"` for one-shot builds that write the manifest, `"false"` when disabled or in watch mode
`process.env.DOMSTACK_SERVICE_WORKER_URL`	Public service-worker URL, usually `/service-worker.js`, or `""` when absent
`process.env.DOMSTACK_SERVICE_WORKER_SCOPE`	Registration scope, usually `/`, or `""` when absent

Compatibility Notes

This is an unstable preview feature and can change outside a major version.
copy is now the output kind for files copied by the generic copy step.
Watch mode intentionally does not write domstack-manifest.json or return results.domstackManifest; it does still build and rebundle the site service worker.

Testing

npm test
npm run test:tsc
npm run test:neostandard
npm run build:declaration
npm run build:schema
node --test lib/identify-pages.test.js test-cases/general-features/index.test.js test-cases/type-exports/index.test.ts test-cases/watch/index.test.js test-cases/template-output-escape/index.test.js
git diff --check

github-actions · 2026-06-15T04:41:39Z

Coverage Report for CI Build 27524398777

Coverage increased (+0.3%) to 92.204%

Details

Coverage increased (+0.3%) from the base build.
Patch coverage: 47 uncovered changes across 2 files (939 of 986 lines covered, 95.23%).
No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
lib/build-output-manifest/index.js	553	520	94.03%
index.js	63	49	77.78%
Total (12 files)	986	939	95.23%

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	5066
Covered Lines:	4806
Line Coverage:	94.87%
Relevant Branches:	886
Covered Branches:	682
Branch Coverage:	76.98%
Branches in Coverage %:	Yes
Coverage Strength:	106.32 hits per line

💛 - Coveralls

socket-security · 2026-06-15T19:50:02Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

socket-security · 2026-06-16T18:03:24Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/json-schema-to-ts@3.1.1

View full report

bcomnes · 2026-07-06T05:04:24Z

-      await writeFile(join(dest, 'domstack-esbuild-meta.json'), JSON.stringify(buildResults.metafile, null, ' '))
+    const serviceWorkerBuildOpts = createServiceWorkerBuildOpts({ buildOpts: extendedBuildOpts, src, siteData })
+    const serviceWorkerBuildResults = serviceWorkerBuildOpts
+      ? await esbuild.build(serviceWorkerBuildOpts)


Does the service worker have its own build?

bcomnes · 2026-07-06T05:06:11Z

-        // @ts-ignore This is fine
-        buildOpts: extendedBuildOpts,
+        outputs,
      },


Does it make sense to make report a single key object. Why not just return outputs as results.

bcomnes · 2026-07-06T05:08:04Z

+ * @param  {...(esbuild.BuildResult | undefined)} results
+ * @returns {esbuild.BuildResult}
+ */
+function mergeBuildResults (...results) {


Is this done efficiently? Would a reduce or for look get this down tone a single iteration?

bcomnes · 2026-07-06T05:08:41Z

+
+  return {
+    inputs: Object.assign({}, ...metafiles.map(metafile => metafile.inputs)),
+    outputs: Object.assign({}, ...metafiles.map(metafile => metafile.outputs)),


Why object adding instead of just spreads

bcomnes · 2026-07-06T05:10:06Z

+ * @param {boolean} params.includeMetafileRecord
+ * @returns {DomstackManifestRecord[]}
+ */
+export function createEsbuildOutputRecords ({ src, dest, siteData, buildResults, includeMetafileRecord }) {


Need to audit for efficiency.

bcomnes · 2026-07-06T05:11:39Z

+ * @param {PageData<any, any, any>} page
+ */
+function extractPrecacheVars (page) {
+  /** @type {{ precache?: unknown, offline?: unknown }} */


What is this? This seems like a peak concern sneaking in to what really should be a manifest collecting feature.

bcomnes · 2026-07-06T05:12:30Z

+      template,
+      outputRecords,
+    })
  } else if (


Are we using exhaustive type narrowing here.

bcomnes · 2026-07-06T05:13:22Z

+ * @param {string} value
+ */
+function toPosix (value) {
+  return value.split(sep).join('/')


There is a version of this that's exported somewhere. Make sure this isn't a double define.

bcomnes · 2026-07-06T05:13:53Z

+ * @param {string} dest
+ * @param {string} filepath
+ */
+function assertInsideDest (dest, filepath) {


Should be a generic helper lib.

bcomnes · 2026-07-06T05:14:56Z

- *   pages: Awaited<ReturnType<typeof pageWriter>>[]
- *   templates: Awaited<ReturnType<typeof templateBuilder>>[]
+ *   outputs: DomstackManifestRecord[]
 * }} PageBuilderReport


Why did this collapse. Double check we should just be dealing with what's in outputs.

bcomnes · 2026-07-06T05:16:41Z

  try {
    const report = await copy(getCopyGlob(src), dest, ...(opts?.ignore ? [{ ignore: opts.ignore }] : []))
-    results.report = report
+    results.report.outputs = createCopiedDomstackManifestRecords({


Double check what this is doing.

bcomnes · 2026-07-06T05:18:13Z

+
+// These schema objects are the source of truth for both runtime manifest validation and
+// the public TypeScript/JSDoc types derived below with json-schema-to-ts.
+/** @satisfies {JSONSchema} */


I don't think this syntax is right this needs to be inline with the type const.

bcomnes · 2026-07-06T05:18:34Z

+  ],
+})
+
+/** @satisfies {JSONSchema} */


Same. Bad satisfies syntax.

bcomnes · 2026-07-06T05:19:30Z

+        precache: {
+          description: 'Application-defined page precache policy metadata. Domstack records this value but does not interpret it.',
+        },
+        offline: {


Seems odd to predefne this capture. Maybe let users configure which keys to capture.

bcomnes · 2026-07-06T05:19:56Z

+  additionalProperties: false,
+})
+
+/** @satisfies {JSONSchema} */


Every schema has bad syntax I'm fairly certain.

bcomnes · 2026-07-06T05:22:08Z

+ * A build step writes these as it emits files. Reconciliation turns them into
+ * revisioned manifest entries.
+ *
+ * @typedef {object} DomstackManifestRecord


These should have descriptions right?

bcomnes · 2026-07-06T05:23:33Z

+// TODO: If a concrete client needs Workbox integration, consider adding an
+// optional derived artifact that projects manifest entries to Workbox's
+// `{ url, revision }` precache shape. Keep the domstack manifest as the richer
+// source of truth until that use case can validate the exact API.


When this is done also confirm we support the right lifecycle hook for workbox. I think it relies on full code gen for the service worker.

bcomnes · 2026-07-06T05:23:54Z

+// `{ url, revision }` precache shape. Keep the domstack manifest as the richer
+// source of truth until that use case can validate the exact API.
+
+const KIND_PRIORITY = new Map([


What is this for?

bcomnes · 2026-07-06T05:24:35Z

+ * @returns {Promise<DomstackManifest>}
+ */
+export async function buildDomstackManifest ({ dest, records = [], entries: existingEntries = [], options = {} }) {
+  /** @type {Map<string, DomstackManifestRecord & { url: string, revision: string | null, bytes: number | null }>} */


Why is this type ugly. Why don't we have a clean type to use here.

bcomnes · 2026-07-06T05:24:58Z

+    setEntry(entryMap, entry)
+  }
+
+  entryMap.delete(toPosix(options.filename ?? DEFAULT_DOMSTACK_MANIFEST_FILENAME))


Should we be deleting records?

bcomnes · 2026-07-06T05:25:32Z

+
+  entryMap.delete(toPosix(options.filename ?? DEFAULT_DOMSTACK_MANIFEST_FILENAME))
+
+  let finalEntries = Array.from(entryMap.values())


We should try to make this all happen in a single pass rather than multiple iterations.

bcomnes · 2026-07-06T05:26:02Z

+ * Create a normalized record for a file inside dest.
+ *
+ * @param {object} params
+ * @param {string} params.dest


Why no descriptions?

bcomnes · 2026-07-06T05:26:40Z

+    kind,
+    url: url ?? outputRelnameToUrl(normalizedOutputRelname),
+    ...(sourceRelname ? { sourceRelname: toPosix(sourceRelname) } : {}),
+    ...(entryPoint ? { entryPoint: normalizeEntryPoint(entryPoint) } : {}),


This is kinda knarly

bcomnes · 2026-07-06T05:27:27Z

+ */
+export function createCopiedDomstackManifestRecords ({ src, dest, report, kind }) {
+  return extractCopiedFiles(report).map(copiedFile => {
+    const filepath = resolve(copiedFile.output)


I wonder if this would better live near cpx2 builder and instead have it just conform to a type over in that file.

bcomnes · 2026-07-06T05:28:04Z

+ */
+export function classifyEsbuildOutput ({ outputRelname, entryPoint, workerOutputRelnames, serviceWorkerOutputRelname }) {
+  const ext = extname(outputRelname)
+


Same here. Closer to es build builder and use a type

bcomnes · 2026-07-06T05:28:33Z

+ * @param {DomstackManifest} domstackManifest
+ * @param {string} [filename]
+ */
+export async function writeDomstackManifest (dest, domstackManifest, filename = DEFAULT_DOMSTACK_MANIFEST_FILENAME) {


We don't have a generic version of this

bcomnes · 2026-07-06T05:29:08Z

+  /** @type {DomstackManifestOptions} */
+  const options = {
+    exclude: [
+      ...((Array.isArray(domstackManifestOpts.exclude) ? domstackManifestOpts.exclude : [])),


Ugly code clean up

bcomnes · 2026-07-06T05:29:36Z

+ * @param {string} relname
+ */
+export function outputRelnameToUrl (relname) {
+  const posixRelname = toPosix(relname)


Double check for dupes

That we didn't define this elsewhere.

bcomnes · 2026-07-06T05:30:08Z

+ * @param {string} value
+ */
+export function toPosix (value) {
+  return value.split(sep).join('/')


Generic helpers should be inserted generic file location

bcomnes · 2026-07-06T05:31:30Z

+ * @param {string[]} exclude
+ */
+function applyExclude (entries, exclude) {
+  if (exclude.length === 0) return entries


Why is manifest dealing with this. Shouldnt it be totally downstream from ignores?

bcomnes marked this pull request as ready for review June 15, 2026 19:50

Copilot AI review requested due to automatic review settings June 15, 2026 19:50

Copilot AI reviewed Jun 15, 2026

bcomnes force-pushed the staic-client-cache branch 2 times, most recently from 31311d7 to 620a4bc Compare June 15, 2026 19:52

bcomnes requested a review from Copilot June 15, 2026 19:53

Copilot AI reviewed Jun 15, 2026

bcomnes force-pushed the staic-client-cache branch 3 times, most recently from fb90546 to e8c79b8 Compare June 16, 2026 18:02

bcomnes force-pushed the staic-client-cache branch from e8c79b8 to f665681 Compare June 17, 2026 03:31

bcomnes force-pushed the staic-client-cache branch 8 times, most recently from a3079c4 to 260af7a Compare June 29, 2026 03:50