Publish a site to Vercel

A Mosaic site is a Next.Js app.

To publish a Next.Js App to Vercel, refer to the Vercel docs.

Deployment

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.

Two deployment shapes

Mosaic supports two production builds in snapshot-file mode:

  1. Default SSR build — yarn build + yarn start (or Vercel's default Next.js runtime). Pages are pre-rendered at build time via generateStaticParams but the Node runtime stays in the deployment so the /api/* route handlers (auth, content-editor preview, cache revalidation webhook) keep working.
  2. Fully static export — yarn build:static:file. Emits a CDN-shippable out/ directory with no Node runtime needed. The /api/* route handlers are replaced with 501 stubs at build time (see scripts/static-export-route-stubs.mjs for 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.

1. Update Config File

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.

2. Set Environment Variables

Set 2 environment variables in the vercel dashboard.

Variable NameValue
MOSAIC_MODEsnapshot-file
MOSAIC_SNAPSHOT_DIRsnapshots/latest
NEXT_PUBLIC_SITE_URLhttps://your-site.example.com (no trailing slash)

NEXT_PUBLIC_SITE_URL

This is the canonical origin of the deployed site. It is read at build/render time by:

  • app/layout.tsx — sets Next's metadataBase, which is what turns relative og:image / twitter:image URLs 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 absolute Sitemap: 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_URL for each preview. Either set NEXT_PUBLIC_SITE_URL per preview, or wire it up in next.config.js to fall back to https://${process.env.NEXT_PUBLIC_VERCEL_URL} when unset.
  • Local dev: falls back to http://localhost:3000 automatically 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.

Mosaic BETA

Coming soon