Static export

When you run a Mosaic site in snapshot-file mode, all of its content is fixed at build time. That means you can pre-render every page to plain HTML and serve the result from any static host — no Node.js runtime required.

The Mosaic site ships a build script that produces a fully-static out/ directory from a local snapshot directory:

yarn build:static:file

The command sets MOSAIC_OUTPUT=export and MOSAIC_MODE=snapshot-file, then invokes next build. The output is a self-contained out/ directory you can upload to S3, Vercel static, Cloudflare Pages, GitHub Pages, or any other static host.

What gets generated

  • Every page enumerated by the snapshot's sitemap.xml (typically every doc in your sources).
  • robots.txt and sitemap.xml.
  • All static assets from public/, including the snapshot's search-records.json.
  • Stubbed app/api/* route handlers that return HTTP 501. These exist only because Next.js refuses to emit a static export when the route files are present but cannot be statically pre-rendered; the stubs are applied automatically before the build and reverted afterwards. You cannot use the auth, preview, revalidate, or search API routes in a static export.

What does not work in a static export

FeatureReasonWorkaround
active modeActive mode reads content from a live Mosaic server on every requestUse snapshot-file for the export build
next.config.js redirects()Not supported by output: 'export'Configure redirects at the hosting layer (S3 redirects, CloudFront Functions, Vercel vercel.json, Nginx, etc.)
/api/auth/* (Auth.js)Auth.js needs a serverAuth-gated sites must run in the regular (non-export) build
/api/content/previewSame — needs a serverEditor preview requires the regular build
/api/revalidateSame — no ISR in a static exportRe-run the build to publish content changes
/api/searchSame — needs a serverSearch /search-records.json in the browser with @jpmorganchase/mosaic-site-middleware/search
next/image optimisationDisabled in export buildsImages are served as-is (images.unoptimized: true)

If your site relies on any of these features, deploy the regular Node build instead. See the publish guide.

How the export build is configured

The exact knobs live in packages/site/next.config.js and packages/site/package.json. Three things differ from the regular build:

  1. A separate config branch. next.config.js switches on process.env.MOSAIC_OUTPUT === 'export' to emit output: 'export', set images.unoptimized: true, and drop redirects(). The config throws loudly if you try to combine MOSAIC_OUTPUT=export with active mode.
  2. generateStaticParams enumerates routes from the sitemap. The catch-all page (app/[namespace]/[...route]/page.tsx) reads the snapshot's sitemap.xml at build time and emits one static page per entry. In non-snapshot builds it short-circuits to a fully-dynamic route.
  3. API route and Server Action stubs. scripts/static-export-route-stubs.mjs backs up each route.ts and Server Action module to <file>.bak and writes a static stub (HTTP 501 + literal dynamic = 'force-static' for routes, a throwing function for actions) before the build, and restores the originals afterwards — even if the build fails. If a build is interrupted, run yarn build:static:revert to restore manually. Because there is no server to load it on demand, the 404 page's header data is read at build time instead.

Serving the output

The out/ directory is a flat tree of .html, .js, .css, image, and font files. Any of the following will serve it correctly:

# Local preview
npx serve out

# AWS S3 + CloudFront
aws s3 sync out s3://your-bucket --delete

# Nginx
location / {
  root /var/www/your-site/out;
  try_files $uri $uri.html $uri/ =404;
}

Note: static hosts typically need try_files $uri $uri.html (or the equivalent) so that /mosaic/index resolves to mosaic/index.html without an explicit .html suffix in the URL.

Mosaic BETA

Coming soon