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.
- Every page enumerated by the snapshot's
sitemap.xml(typically every doc in your sources). robots.txtandsitemap.xml.- All static assets from
public/, including the snapshot'ssearch-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.
| Feature | Reason | Workaround |
|---|---|---|
active mode | Active mode reads content from a live Mosaic server on every request | Use 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 server | Auth-gated sites must run in the regular (non-export) build |
/api/content/preview | Same — needs a server | Editor preview requires the regular build |
/api/revalidate | Same — no ISR in a static export | Re-run the build to publish content changes |
/api/search | Same — needs a server | Search /search-records.json in the browser with @jpmorganchase/mosaic-site-middleware/search |
next/image optimisation | Disabled in export builds | Images 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.
The exact knobs live in packages/site/next.config.js and
packages/site/package.json. Three things differ from the regular build:
- A separate config branch.
next.config.jsswitches onprocess.env.MOSAIC_OUTPUT === 'export'to emitoutput: 'export', setimages.unoptimized: true, and dropredirects(). The config throws loudly if you try to combineMOSAIC_OUTPUT=exportwithactivemode. generateStaticParamsenumerates routes from the sitemap. The catch-all page (app/[namespace]/[...route]/page.tsx) reads the snapshot'ssitemap.xmlat build time and emits one static page per entry. In non-snapshot builds it short-circuits to a fully-dynamic route.- API route and Server Action stubs.
scripts/static-export-route-stubs.mjsbacks up eachroute.tsand Server Action module to<file>.bakand writes a static stub (HTTP 501 + literaldynamic = '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, runyarn build:static:revertto restore manually. Because there is no server to load it on demand, the 404 page's header data is read at build time instead.
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/indexresolves tomosaic/index.htmlwithout an explicit.htmlsuffix in the URL.