Deployment

purestack publish prepares a local release directory. Your hosting provider or deployment pipeline uploads that directory. Before uploading, verify the generated artifact with the same public path and routing that the production host will use.

Keep source and output separate

Set explicit output paths in content/siteConfig.json:

{
  "siteTitle": "Acme Docs",
  "outDir": "../dist/site",
  "publishDir": "../dist/publish"
}

These paths resolve from the content directory. build and serve use dist/site; publish uses dist/publish. Keep both outside content so generated assets are not rediscovered as source assets. publish cleans publishDir, so that directory must contain only disposable build output.

Build the release

From the project root, using your installed CLI:

yarn purestack publish --content ./content

The command cleans the release directory, minifies generated HTML and bundled browser scripts, disables CSS pretty printing, and treats script asset failures as errors. It loads content/purestack.config.ts if present. Plugins writing extra files should use context.config.outDir, which points to publishDir for this build.

The artifact contains route directories with index.html, generated theme styles under assets/, copied static assets, referenced browser bundles, and optional Pagefind, sitemap, and robots outputs. Deploy the complete artifact so HTML and the script filenames it references come from the same build.

Configure the public mount path

basePath changes URLs, not the directory tree in the artifact. It does not create dist/publish/docs/. Configure the host to serve dist/publish/index.html at /docs/ and nested route directories at their corresponding URLs.

A static host must serve directory indexes: /guides/install/ maps to guides/install/index.html. Check a nested URL directly, including after a browser refresh. Hidden locale URLs need additional host-side language routing; prefixed locale URLs already map to separate directories.

Verify the release rather than only the preview

purestack serve is a development server that rebuilds into outDir; it is not a command for serving an existing release directory unchanged. Use your host's local preview or a static file server pointed at publishDir to inspect the artifact over HTTP.

Before upload, verify these concrete outcomes:

1. The home page and a nested page load directly at the intended base path.
2. Light and dark styles, images, and browser scripts return successfully.
3. One interactive example responds to input with no browser console error.
4. Search returns a known page, if enabled. Read Pagefind diagnostics even if the build succeeded.
5. Canonical and sitemap URLs use the production origin, and preview images exist.
6. Pages marked index: false are absent from the sitemap and search index.

The generated HTML contains build-time values and public browser code. Do not put private credentials in frontmatter or browser entry points. auth.enabled controls account UI; enforce actual access restrictions in your application or host.

Account for development-only behavior

Live reload, diagnostic error pages, watched rebuilds, locale preference handling, and plugin devMiddleware belong to the development server. They are not a production server shipped by publish. A browser app calling a mock endpoint needs a corresponding deployed endpoint or an explicit production API URL.

Troubleshoot a deployment