A Mosaic site is a Next.Js app.
To publish a Next.Js App to Vercel, refer to the Vercel docs.
As the vercel platform hosts static content you will need to deploy a mosaic snapshot. There is no option to run mosaic in active mode.
Mosaic supports two production builds in snapshot-file mode:
- Default SSR build —
yarn build+yarn start(or Vercel's default Next.js runtime). Pages are pre-rendered at build time viagenerateStaticParamsbut the Node runtime stays in the deployment so the/api/*route handlers (auth, content-editor preview, cache revalidation webhook) keep working. - Fully static export —
yarn build:static:file. Emits a CDN-shippableout/directory with no Node runtime needed. The/api/*route handlers are replaced with 501 stubs at build time (seescripts/static-export-route-stubs.mjsfor the why), so this target is for read-only sites with no auth and no in-browser content editor.
The instructions below assume the default SSR build. For the static
target, point your hosting at out/ instead of letting Vercel build
Next normally.
Add the following to the next config file used by your site:
outputFileTracingIncludes: {
'/*': ['snapshots/**/*']
},Output File Tracing is a feature of Next.js that uses static analysis to determine what files are needed to deploy a production version of an application.
Due to the architecture of mosaic, snapshot files can be ignored by this process and therefore excluded from the build artifacts deployed by vercel.
Set 2 environment variables in the vercel dashboard.
| Variable Name | Value |
|---|---|
| MOSAIC_MODE | snapshot-file |
| MOSAIC_SNAPSHOT_DIR | snapshots/latest |
| NEXT_PUBLIC_SITE_URL | https://your-site.example.com (no trailing slash) |
This is the canonical origin of the deployed site. It is read at build/render time by:
app/layout.tsx— sets Next'smetadataBase, which is what turns relativeog:image/twitter:imageURLs in your per-page metadata into absolute URLs that social-card unfurlers (Slack, X, LinkedIn, Discord, iMessage, etc.) can actually resolve.app/sitemap.ts— emits absolute<loc>entries in/sitemap.xml.app/robots.ts— emits the absoluteSitemap:line in/robots.txt.
Set this per environment:
- Production: your real public hostname, e.g.
https://docs.example.com. - Preview deployments: Vercel exposes
NEXT_PUBLIC_VERCEL_URLfor each preview. Either setNEXT_PUBLIC_SITE_URLper preview, or wire it up innext.config.jsto fall back tohttps://${process.env.NEXT_PUBLIC_VERCEL_URL}when unset. - Local dev: falls back to
http://localhost:3000automatically if unset.
If the variable is missing in a production build the site still works, but
absolute URLs in metadata/sitemap/robots will fall back to localhost and
social cards / SEO will be broken. The site logs a warning at boot in that
case. If it is set but isn't an absolute http(s) URL, the site refuses to
start.