Add build output manifest for static caching

[bcomnes]

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]

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]

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]

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]

Dont need this callout here. We can link to it in the manifest docs.

[bcomnes]

This section should not be deleted.

[bcomnes]

This note should not be deleted.

[bcomnes]

This section should not have been removed.

[bcomnes]

The page vars caveats should not have been deleted.

[bcomnes]

I thought I removed this in favor of the esbuild settings file. Maybe we should remove this in this upcoming v12 release.

[bcomnes]

This should go in the settings file as well.

[bcomnes]

Need to audit this file array