Migrate to the App Router

The reference Mosaic site (packages/site) has moved from the Next.js Pages Router to the App Router. A follow-up release secured the editor and the content server, changed some deployment defaults, and removed snapshot-s3 mode and mosaic upload. This guide covers everything you need to change if your site was copied from the old Pages Router site, or if you run the Mosaic CLI (mosaic serve, mosaic build or mosaic upload).

Your site uses the old layout if it has src/pages/_app.tsx and src/pages/[...route].tsx.

Content authors don't need to change anything. Pages are still MDX with the same frontmatter, and references such as {meta.title} still work.

Start from a fresh export of the current packages/site, following Create a Site, and move your customisations into it, rather than converting your old files in place. The export converts workspace dependencies to published version ranges. Almost every file in the site has changed, and the new files contain fixes you'd otherwise have to rediscover. The site's README.md lists the patterns you must keep under "Critical patterns to preserve when copying".

Keep your mosaic.config.mjs, your content, your CSS and your own components. Then work through the sections below.

Before you start

  • Node.js 24 or later. The reference Docker images use Node.js 24.
  • Next.js 16.4.2 or later, and React 19. Earlier Next.js 16 releases (and 15.x before 15.5.28) are affected by remote code execution and denial of service advisories (GHSA-2xp9-vwfh-vxw4, GHSA-p293-qw3h-jr36, GHSA-2464-fhr4-w9xw, GHSA-p3m5-59mp-jv5r).
  • Upgrade every @jpmorganchase/mosaic-* package to the same version. mosaic-site-middleware, mosaic-site-components and mosaic-layouts have breaking changes, so don't mix old and new versions.
  • For hosts using Auth.js, install next-auth v5 (next-auth@^5.0.0-beta) in place of v4 and add the Mosaic adapter described below. Hosts without authentication do not need this package.
  • mosaic-site-middleware, mosaic-site-components and mosaic-layouts now list next as a peer dependency. Your site must depend on next directly, which it normally does already.

1. Find where each file has moved

Pages Router siteApp Router site
src/pages/_app.tsxsrc/app/layout.tsx (HTML shell, fonts, global CSS, site-wide metadata) and src/app/providers.tsx (provider stack)
src/pages/_document.tsxsrc/app/layout.tsx
src/pages/[...route].tsxsrc/app/[namespace]/[...route]/page.tsx
src/pages/index.tsx (redirect)src/app/page.tsx
src/pages/api/auth/[...nextauth].tssrc/auth.ts and src/app/api/auth/[...nextauth]/route.ts
src/pages/api/content/preview.tssrc/app/[namespace]/[...route]/previewAction.ts (Server Action)
Browser WebSocket to the CLI's /workflowssrc/app/[namespace]/[...route]/persistAction.ts (Server Action) and src/app/api/workflows/[jobId]/events/route.ts
components object in _app.tsxsrc/app/[namespace]/[...route]/MdxComponents.ts
Metadata component with next/headgenerateMetadata in src/app/[namespace]/[...route]/page.tsx
src/types/mosaic.tsRemoved
.eslintrc.jseslint.config.mjs
.env.local (committed).env.development
.env.prod.env.production

The new site also adds files that have no Pages Router equivalent:

  • [namespace]/layout.tsx, which loads the data shared by a namespace (/mosaic/...) once and keeps the header mounted while readers navigate (see Providers, theme and layouts)
  • [namespace]/page.tsx, which renders paths with no segments after the namespace, such as /mosaic and root-level documents like /about, with the catch-all's page. Use a required catch-all ([...route]), not an optional one ([[...route]]): Next.js treats an optional catch-all whose only value is index as empty, so /mosaic/index was served from the /mosaic page and the header's prefetch of it repeated without end on 404 pages
  • not-found.tsx, [namespace]/not-found.tsx, error.tsx and global-error.tsx
  • robots.ts and sitemap.ts
  • api/revalidate/route.ts, which clears cached content when the CLI reports an update
  • api/content/live and api/content/ready, which reload pages in next dev when content changes, including pages that returned 404 while the CLI was still loading

next.config.js is now split into a base config, a config used only when the site runs on a server, and a config for static export.

If your site uses the content editor, copy experimental.serverActions.bodySizeLimit from the reference next.config.js. Next.js rejects Server Action requests over 1 MB by default, so without it saves of large pages fail before they reach the CLI.

2. Move your customisations

MDX components

The old _app.tsx merged your components into components and passed them to every page. Add them to hostComponents in src/app/[namespace]/[...route]/MdxComponents.ts instead:

- // src/pages/_app.tsx
- const components = { ...mosaicComponents, Salt: saltComponents, Sitemap, ReleaseNotes };
+ // src/app/[namespace]/[...route]/MdxComponents.ts
+ const hostComponents = { Salt, Sitemap, ReleaseNotes };

The file is marked 'use client', so the components it registers must work in the browser.

Providers, theme and layouts

_app.tsx wrapped every page in a single provider stack, so the header and the rest of the frame stayed mounted between pages. The App Router site splits that into three parts:

  • Providers (src/app/providers.tsx) wraps the whole site and is mounted once by layout.tsx. It holds ColorModeProvider and ThemeProvider, plus the session provider and Mosaic auth adapter when authentication is enabled.
  • NamespaceFrame (src/app/[namespace]/NamespaceFrame.tsx) is mounted by [namespace]/layout.tsx and stays mounted while readers navigate under the same leading URL segment. It receives the frame's fallback shared config and renders the header. A page passes its canonical content route, resolved shared config and edit state to the header with <FrameSync>. Relative links and images use the canonical route even when the browser is visiting an alias. Search is managed separately by the root SearchProvider.
  • StoreShell (src/app/providers.tsx) wraps each page and is mounted by page.tsx. It holds the page's store, BaseUrlProvider, ImageProvider, LinkProvider and LayoutProvider. Layouts leave the header out because NamespaceFrame renders it.

To add your own layouts, pass layoutComponents={{ ...mosaicLayouts, MyLayout }} to StoreShell. Import global CSS and fonts in layout.tsx.

Salt adds its component styles and its theme settings (density, accent, corners and fonts) in the browser, after the page hydrates. Without them in the server HTML, every page changes size as it hydrates. The reference layout.tsx adds them to the server HTML, and your layout.tsx should do the same:

  • Import @jpmorganchase/mosaic-site-preset-styles/index.css, which already includes Salt core and icon styles. Hosts using additional Salt packages should import those packages' styles as needed.
  • Set data-accent, data-corner, data-heading-font and data-action-font on <html>, with the values ThemeProvider passes to Salt.
  • Use the inline theme script from src/lib/themePrefScript.ts. It sets data-mode and Salt's density class before the first paint.

[namespace]/page.tsx renders single-segment documents and aliases, such as /about or /quickstart; [namespace]/[...route]/page.tsx renders deeper paths. The first URL segment is only a boundary for the persistent frame; it does not have to match a source's namespace or prefixDir. Folder index URLs continue to resolve through the content loaders. The sidebar stays with each page so it follows updated content.

Initial server HTML uses the layout's fallback config and the index route associated with that config. <FrameSync> applies the page's canonical route and config before the first client paint; layouts do not receive their child page's route data.

Without authentication, omit both auth providers. Mosaic's auth hook defaults to signed out with login disabled; it makes no session requests:

<ColorModeProvider>
  <ThemeProvider themeClassName={themeClassName}>{children}</ThemeProvider>
</ColorModeProvider>

For Auth.js, mount NextAuthAdapter inside SessionProvider. This is a required migration: an existing SessionProvider alone no longer connects Mosaic's UI to the session. The reference host mounts this pair only when AUTH_ENABLED is true. It leaves the session unresolved on the server and fetches it after mount:

'use client';
import { SessionProvider } from 'next-auth/react';
import { NextAuthAdapter } from '@jpmorganchase/mosaic-site-components/auth/next-auth';

<SessionProvider>
  <NextAuthAdapter loginEnabled>
    <ColorModeProvider>
      <ThemeProvider themeClassName={themeClassName}>{children}</ThemeProvider>
    </ColorModeProvider>
  </NextAuthAdapter>
</SessionProvider>;

If omitted, the adapter's loginEnabled prop follows NEXT_PUBLIC_ENABLE_LOGIN. It supplies the session user, loading status, sign-in/sign-out actions and a stable sign-in link. Other authentication systems can provide the structural MosaicAuthValue through MosaicAuthProvider from @jpmorganchase/mosaic-site-components/auth. This context controls UI only: keep write authorization on the server.

Trying a snapshot

Snapshots use 0.0.0-snapshot-<timestamp> intentionally, so they do not satisfy ordinary ^0.1.0-beta.x ranges. Install one exact snapshot version for all of the host's Mosaic packages. Extensions should use peer dependencies and externalize them, rather than installing their own Mosaic runtime.

At the host's package root, pin each Mosaic package in its dependency graph to the same snapshot using Yarn resolutions. For example, this excerpt uses the published 0.0.0-snapshot-20261115213905 cohort:

{
  "dependencies": {
    "@jpmorganchase/mosaic-components": "0.0.0-snapshot-20261115213905",
    "@jpmorganchase/mosaic-store": "0.0.0-snapshot-20261115213905"
  },
  "resolutions": {
    "@jpmorganchase/mosaic-components": "0.0.0-snapshot-20261115213905",
    "@jpmorganchase/mosaic-store": "0.0.0-snapshot-20261115213905"
  }
}

Repeat the resolution for every Mosaic package used directly or transitively; the two entries above illustrate the syntax. That older snapshot does not contain all changes in this guide: choose a cohort containing the fixes you need. Yarn can still warn that an extension's normal-release peer range excludes the snapshot. Test that extension against the preview and explicitly support the tested version when needed; do not permanently widen published peer ranges to every snapshot merely to silence warnings.

Data from your own middleware

getServerSideProps and the middleware chain (createMiddlewareRunner, middlewarePresets) are gone. Fetch your data in src/app/[namespace]/[...route]/page.tsx instead:

  1. Write an async function that loads the data. Wrap it in React's cache() if generateMetadata also needs it, so it runs once per request.
  2. Call it inside the existing Promise.all next to resolveContent. Search is loaded independently by the header through the records API or browser index.
  3. Pass the result to your component as a prop, or add it to storeProps and read it with useStore from @jpmorganchase/mosaic-store.
const [resolved, sp, releaseNotes] = await Promise.all([
  resolveContent(pathname, mode, contentUrl),
  shouldPrerenderSnapshot ? Promise.resolve({}) : searchParams,
  getReleaseNotes(pathname)
]);

Snapshot builds pre-render pages, so this function runs at build time there.

Page metadata

generateMetadata in page.tsx builds the title, description and Open Graph tags from frontmatter. Add per-page tags there, and site-wide tags to the metadata export in layout.tsx. Don't add the old Metadata component back; it would duplicate every tag.

  • Replace next/router with next/navigation (useRouter, usePathname, useSearchParams), and add 'use client' to the top of the file.
  • Components that use hooks, context or browser APIs need 'use client', either in their own file or in the file that imports them.
  • router.events doesn't exist in the App Router, so useIsLoading and Fade have been removed.
  • Don't call useSearchParams() in components that render on pre-rendered pages. It makes Next.js render those pages in the browser instead. To check whether the editor is open, use useIsEditing() from @jpmorganchase/mosaic-content-editor-plugin/useEditMode.

API routes

Move each src/pages/api/<name>.ts handler to src/app/api/<name>/route.ts, exporting GET, POST and so on, using the web Request and Response types.

If you use static export, add your route to ROUTES in scripts/static-export-route-stubs.mjs. Next.js won't export a route handler unless it is marked as static, and that script does this for you during build:static:*.

To serve your docs as Markdown for agents (/llms.txt and /<page>.md), copy src/app/api/llms/[...path]/route.ts, its rewrites in next.config.js and its entry in scripts/static-export-route-stubs.mjs from the reference site. See LlmsTxtPlugin.

Home page redirect

src/app/page.tsx redirects / to /mosaic/index. Change the target to your own namespace.

3. Update the package APIs you call

PackageRemovedUse instead
mosaic-site-middlewarewithMosaicMode, withMDXContent, withSharedConfig, withSearchIndex, withSession, middlewarePresets, createMiddlewareRunner, fromGetServerSidePropsContextresolveMosaicMode, resolveContent, canonicalRoute, getMdxRaw, getMdxRawSource, getSharedConfig, getTagSuggestions, loadSitemap and serializeMdxForClient. Use auth() from src/auth.ts for the session.
mosaic-site-componentsBody, Document, the OpenAPI MDX componentcreateMdxRenderer with serializeMdxForClient (see BodyServer.tsx), and src/app/layout.tsx. For OpenAPI, see below.
mosaic-layoutsuseIsLoading, FadeNothing. Pass isEditing to LayoutProvider.
mosaic-content-editor-pluginuseContentEditor, usePageStateEditorProvider and its hooks (usePreviewContent, useSaveState, useErrorMessage, …), and useEditMode, useIsEditing, useEditModeActions
mosaic-storeSiteState.colorMode, SiteState.actions, registerStore, disposeStoreMount one ColorModeProvider above ThemeProvider and the content stores. Use useColorMode() and useStoreActions().setColorMode(). initializeStore and reseedStore manage page data without theme synchronization.

The root theme provider keeps the existing mosaic-theme-pref saved preference format. Remove any root content store used only for colour mode; keep the page and persistent-header content stores. Replace direct useStore(state => state.colorMode) and useStore(state => state.actions) selectors with the theme hooks above. Content stores no longer need registration or disposal effects.

mosaic-schemas no longer exports snapshotS3EnvSchema or S3LoaderProcessEnv, and MosaicMode in mosaic-types is now 'active' | 'snapshot-file'.

@jpmorganchase/mosaic-open-api-component is no longer published, and <OpenAPI> is no longer a default MDX component. Pages that use it fail to render, so link to your API's hosted Swagger UI instead, or add your own component to hostComponents. Remove the package from your dependencies and from transpilePackages in next.config.js.

The loaders are cached and tagged with MOSAIC_CONTENT_CACHE_TAG. Import the tag from @jpmorganchase/mosaic-site-middleware/cache-tags if you revalidate it yourself.

For a page and its configuration, use resolveContent(pathname, mode, contentUrl) from @jpmorganchase/mosaic-site-middleware. It follows folder-to-index redirects and reads an alias's configuration from the backing document's folder. On success, mdx contains the raw document and parsed frontmatter, pathname is its public canonical URL, and sourcePathname is its backing path (including .md or .mdx when supplied by the source). Use pathname for metadata and relative navigation, and sourcePathname for raw-source reads and the editor’s route prop used for saves. The requested alias remains in originalPathname.

The returned sharedConfig is the folder's configuration with the page's authored sharedConfig (for example a per-page header or footer) on top, and mdx.frontmatter.sharedConfig holds the same value. sourceCapabilities always comes from the folder's configuration, so content can't grant itself capabilities such as editing. You don't need to merge them yourself. A missing page retains the requested folder's configuration for the create-page flow; an authored public permalink does not change its backing source or capabilities.

The editor plugin now uses Lexical 0.45 instead of 0.17:

- import { useContentEditor, usePageState } from '@jpmorganchase/mosaic-content-editor-plugin';
+ import {
+   EditorProvider,
+   usePreviewContent,
+   useSaveState
+ } from '@jpmorganchase/mosaic-content-editor-plugin';

Import editor code from subpaths such as @jpmorganchase/mosaic-content-editor-plugin/useEditMode. The package root includes the whole editor, so importing from it adds the editor to every page.

4. Update sign-in (Auth.js v5)

  • src/auth.ts holds the Auth.js configuration, and src/app/api/auth/[...nextauth]/route.ts exports its handlers. On the server, call auth() instead of getServerSession().
  • Rename NEXTAUTH_SECRET to AUTH_SECRET. The old name still works. Generate a secret with openssl rand -base64 32.
  • Remove NEXTAUTH_URL. The site trusts the request's host instead.
  • Set MOSAIC_AUTH_ENABLED=true to turn sign-in on.
  • GITHUB_ID, GITHUB_SECRET and the GitHub callback URL (/api/auth/callback/github) haven't changed.
  • Set MOSAIC_EDITORS. It lists who may sign in and edit: comma-separated emails, @domains, or *. Emails and @domains only match email addresses that GitHub has verified. If it isn't set, nobody can sign in in production. Set MOSAIC_EDITORS=* to keep the old behaviour, where anyone who could sign in could edit.
  • In production, the site rejects the placeholder AUTH_SECRET from .env.development.
  • In next dev, MOSAIC_DEV_FAKE_AUTH=true signs you in as a test user without GitHub.

5. Update editing and saving

  • The editor only appears on pages from a writable source. A source must declare capabilities: { writable: true }. source-git-repo does; source-local-folder, source-http and the other read-only sources don't. If you wrote your own source and want it to be editable, add capabilities to it. Frontmatter can't turn editing on.
  • Preview and save now run on the site's server. The browser no longer connects to the CLI. Replace NEXT_PUBLIC_MOSAIC_WORKFLOWS_URL with MOSAIC_WORKFLOWS_URL, which is only read on the server.
  • Saves no longer use WebSockets. Set MOSAIC_WORKFLOWS_URL to the CLI's base HTTP URL, such as http://mosaic-fs:8080. The site starts a save with an HTTP request to the CLI, and the editor follows its progress with Server-Sent Events through the site's /api/workflows/<jobId>/events route. An old ws://…/workflows value still works, but logs a warning.
  • Set MOSAIC_WORKFLOWS_SECRET to the same value on the site and the CLI. If the CLI doesn't have it, no save will run.
  • Saves that take longer than MOSAIC_WORKFLOWS_TIMEOUT_MS (set on the CLI, 5 minutes by default) are reported as failed.
  • Authors can create new pages from the editor.
  • In next dev, MOSAIC_DEV_BYPASS_CAPABILITY_GATE=true shows the editor on every page. It has no effect in production.

6. Update environment variables

Env files

BeforeNowWhy
.env.local.env.developmentNext.js loads .env.local in production too. Only next dev loads .env.development, so its placeholder secrets and dev-only flags can't reach a production build.
.env.prod.env.productionNext.js never loaded .env.prod. It loads .env.production for next build and next start.

Don't commit real secrets to either file. Set them in your hosting environment, or in .env.local or .env.production.local, which git ignores.

If your mosaic.config.mjs loads env files with @next/env, only load the development files when asked to: loadEnvConfig(projectDir, process.env.NODE_ENV === 'development'). Then set NODE_ENV=development in the scripts that run the CLI locally, as the reference site's serve, debug and gen:snapshot scripts do. Otherwise a mosaic serve started without NODE_ENV would pick up the placeholder secrets from .env.development.

Production builds now default to snapshot mode. .env.production sets MOSAIC_MODE=snapshot-file. If your site reads content from a running Mosaic CLI, set MOSAIC_MODE=active explicitly. Values set in the environment take precedence over .env.production.

Both the site and the CLI check their variables when they start. A production site (next start or the standalone server.js) and mosaic serve exit with code 1 on an invalid value, and list every problem as NAME: reason; next dev only logs the list. next build doesn't check runtime variables, so you can still build an image without them. Copy src/instrumentation.ts and src/lib/config.ts from the reference site to get the site checks. The full lists, with types and defaults, are in the site README and the Admin page.

snapshot-s3 mode is removed. MOSAIC_MODE is now active or snapshot-file, and the reference site refuses to start or build with any other value. If you kept snapshots in S3, download the snapshot folder before you build (for example aws s3 sync s3://your-bucket snapshots/latest), then set MOSAIC_MODE=snapshot-file and point MOSAIC_SNAPSHOT_DIR at that folder, relative to the site's folder. The build:static:s3 and serve:snapshot:s3 scripts are gone too; use build:static:file and serve:snapshot:file.

Site: renamed or removed

BeforeNow
NEXTAUTH_SECRETAUTH_SECRET (NEXTAUTH_SECRET still works)
NEXTAUTH_URLRemove
NEXT_PUBLIC_MOSAIC_WORKFLOWS_URLMOSAIC_WORKFLOWS_URL, plus MOSAIC_WORKFLOWS_SECRET
NEXT_PUBLIC_MOSAIC_IBCE_PREVIEW_URLRemove. Preview is a Server Action.
OPTIMIZE_IMAGESNEXT_PUBLIC_OPTIMIZE_IMAGES
MOSAIC_ENABLE_SOURCE_PUSHRemove. Nothing reads it.
MOSAIC_S3_*Remove, with snapshot-s3 mode (see above).

Site: new

VariablePurpose
MOSAIC_AUTH_ENABLEDtrue turns sign-in on.
MOSAIC_EDITORSWho may sign in and edit. If it isn't set, nobody can in production.
MOSAIC_WORKFLOWS_SECRETShared secret for saves. Use the same value as the CLI.
NEXT_PUBLIC_SITE_URLThe site's public URL, used for canonical URLs, sitemap.xml and robots.txt. Set it at build time.
MOSAIC_REVALIDATE_SECRETProtects POST /api/revalidate. Use the same value as the CLI.
MOSAIC_ACTIVE_MODE_CACHEtrue caches content in active mode until the CLI calls /api/revalidate. Only use it if that call reaches every site instance.
MOSAIC_DEV_FAKE_AUTH, MOSAIC_DEV_BYPASS_CAPABILITY_GATE, MOSAIC_DISABLE_LOADER_CACHEOnly for next dev.

These haven't changed: MOSAIC_MODE (apart from the removed snapshot-s3 value), MOSAIC_ACTIVE_MODE_URL, MOSAIC_SNAPSHOT_DIR, GITHUB_ID, GITHUB_SECRET, NEXT_PUBLIC_ENABLE_LOGIN and SITE_URL.

CLI: new

VariablePurpose
MOSAIC_WORKFLOWS_SECRETRequired for saves. The workflows endpoints (/workflows/jobs) refuse any request without it.
MOSAIC_WORKFLOWS_TIMEOUT_MSHow long a save may take before it is reported as failed (default 5 minutes). It used to be read by the site.
MOSAIC_ADMIN_SECRETProtects the admin API. Send it in the x-mosaic-admin-secret header, as a bearer token, or as the password in the browser's login prompt. If it isn't set, the admin API is only open when NODE_ENV=development.
MOSAIC_CORS_ORIGINSComma-separated origins allowed to call the CLI from a browser. CORS is now off by default.
MOSAIC_REVALIDATE_URL, MOSAIC_REVALIDATE_SECRETWhen both are set, the CLI calls the site's /api/revalidate whenever a source updates. mosaic serve refuses to start when the URL is set without the secret.
MOSAIC_BITBUCKET_WEBHOOK_SECRETOptional. Enables POST /_mosaic_/webhooks/bitbucket, which refreshes git repo sources as soon as Bitbucket reports a push. See Refresh on push.

7. Check how the CLI behaves

  • The /workflows WebSocket is gone. Saves start with POST /workflows/jobs and report progress as Server-Sent Events from GET /workflows/jobs/:jobId/events. See Workflows.
  • CORS is off by default. The CLI used to allow every origin. The site calls the CLI from its server, so it doesn't need CORS. Only set MOSAIC_CORS_ORIGINS if a browser calls the CLI directly.
  • The admin API needs a secret outside development. Only /_mosaic_/tags/list stays open. If an SSO proxy in front of the CLI uses the Authorization header, send the secret in x-mosaic-admin-secret.
  • mosaic build empties the snapshot folder (--out joined with --name) before writing it, so deleted pages no longer linger. It rejects a --name that points at the output folder itself or outside it, such as . or ../x.
  • mosaic upload is removed, with its -S / --snapshot option. If you still want a copy of your snapshots in S3, upload the folder yourself, for example with aws s3 sync snapshots/latest s3://your-bucket.
  • Sources now honour requestTimeout. The HTTP, Readme, Storybook and Figma sources apply it, and it defaults to 5 seconds. Raise requestTimeout for any source that regularly takes longer to respond.

8. Deploy

  • Docker: the reference Dockerfiles use Node.js 24 and set MOSAIC_MODE=active in both the build and run stages. Do the same in your own images if they read from a running CLI. They also set MOSAIC_OUTPUT=standalone in the build stage, which makes next.config.js emit the .next/standalone server they copy into the runtime image.
  • Network: only the site's server needs to reach the CLI, through MOSAIC_ACTIVE_MODE_URL and MOSAIC_WORKFLOWS_URL, over plain HTTP. You no longer need to expose the CLI to browsers or allow WebSockets. Proxies must not buffer text/event-stream responses, from the CLI or from the site's /api/workflows/ routes. If you run several CLI instances, a save's progress must be read from the instance that started it.
  • Static export (optional): yarn build:static:file builds a fully static out/ folder that any CDN can serve. See Static export.
  • Security headers: the reference next.config.js sends Content-Security-Policy: frame-ancestors 'self'; object-src 'none'; base-uri 'self', X-Frame-Options, X-Content-Type-Options and Referrer-Policy, and turns off X-Powered-By. Copy them into your config. A static export ignores next.config.js headers, so set them in your hosting layer instead. If other sites embed your pages, add their origins to frame-ancestors.
  • Snapshots: rebuild your snapshots with the new mosaic build.
  • Prerender routes: regenerate snapshots to include mosaic-routes.json. Use generateMosaicStaticParams({ pageExtensions: ['.mdx'] }) from @jpmorganchase/mosaic-site-middleware/routes instead of deriving static params from loadSitemap(). Keep the required catch-all/root-page split; the helper returns both forms. Sitemap exclusions now affect SEO only. See snapshot route inventory for selection, empty-host and legacy-snapshot behavior.

Checklist

  1. Use Node.js 24 or later.
  2. Upgrade all @jpmorganchase/mosaic-* packages to the same version. Auth.js hosts also upgrade next-auth to v5 and mount NextAuthAdapter inside SessionProvider.
  3. Export the current packages/site using Create a Site and move your components, layouts, CSS and config into it.
  4. Replace next/router imports and move pages/api handlers to app/api route handlers.
  5. Rename .env.local to .env.development and .env.prod to .env.production, and rename the env vars listed above.
  6. Set AUTH_SECRET, MOSAIC_AUTH_ENABLED and MOSAIC_EDITORS on the site.
  7. Set the same MOSAIC_WORKFLOWS_SECRET on the site and the CLI.
  8. Set MOSAIC_ADMIN_SECRET, and MOSAIC_CORS_ORIGINS if needed, on the CLI.
  9. Set MOSAIC_MODE=active if your site reads from a running CLI, or MOSAIC_MODE=snapshot-file if it used snapshot-s3.
  10. Set NEXT_PUBLIC_SITE_URL when you build the site.
  11. Run yarn build && yarn start, open a few pages, sign in, then edit and save a page from a Git source.

Search records migration

The default header now uses section-level search. Remove getSearchData, useSearchIndex, and the searchIndex/searchConfig store props from custom integrations. Regenerate snapshots: the three legacy search files are no longer emitted. Server sites use /api/search; static exports use a lazy browser index from search-records.json. See search configuration for provider and plugin migration details.

Reusing metadata and live authoring

App Router hosts can import buildMosaicMetadata from @jpmorganchase/mosaic-site-middleware/metadata and pass the result of resolveContent. It returns document title, description, canonical URL and the historic lastModified/breadcrumb meta tags; missing documents and redirects return an empty object. This module is pure and does not load content. Keep metadataBase, Open Graph/Twitter branding and image policy in your host.

The /client entrypoint exports CanonicalizeUrl and LiveReload. Mount CanonicalizeUrl only after the host's folder/index check; arbitrary aliases should keep their URL. It preserves the router's history state, query and hash. LiveReload refreshes the Next router on each content change and accepts an endpoint (default /api/content/live) and optional onContentChanged callback for host-owned caches. Render it only in development.

Node route adapters can use these narrow server imports:

import { createLiveReloadHandler } from '@jpmorganchase/mosaic-site-middleware/live-reload';
import { createRevalidateHandler } from '@jpmorganchase/mosaic-site-middleware/revalidate';

export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';

// In separate route.ts files:
export const GET = createLiveReloadHandler({
  isDevelopment: () => process.env.NODE_ENV === 'development'
});
export const POST = createRevalidateHandler({
  getSecret: () => ({ secret: process.env.MOSAIC_REVALIDATE_SECRET })
});

The host must apply its own placeholder/production secret policy in getSecret; an absent secret fails closed with 503, and invalid credentials return 401. The webhook accepts x-mosaic-revalidate-secret or a Bearer token, immediately expires the content cache tag, then notifies connected development clients only after invalidation succeeds. The /live-reload/bus entrypoint exports notifyContentChanged and subscribeContentChanged for custom Node adapters. This bus is local to one process and survives development HMR; it is not a cross-process or distributed messaging service. Streams clean up on request abort, cancellation and failed writes. Static-export hosts must omit/stub these runtime routes, as the reference host already does.

Reusable host composition

A custom App Router host can import NamespaceFrame and StoreShell from @jpmorganchase/mosaic-layouts/host, with FrameSync from @jpmorganchase/mosaic-store/frame. Mount the namespace frame in the persistent layout, then put a shell and sync component in each page:

<NamespaceFrame data={namespaceFallback} header={<CustomHeader />}>
  <StoreShell
    storeProps={pageData}
    isEditing={isEditing}
    layoutComponents={customLayouts}
    imageComponent={CustomImage}
    linkComponent={CustomLink}
  >
    <FrameSync
      route={canonicalDocumentRoute}
      sharedConfig={pageData.sharedConfig}
      isEditing={isEditing}
    />
    {children}
  </StoreShell>
</NamespaceFrame>

In a real App Router tree the frame and page shell belong to different route files. Keep one root ColorModeProvider above them. NamespaceFrame accepts the same image/link renderer slots as StoreShell; its optional header defaults to Mosaic's app header. StoreShell also forwards defaultLayout and LayoutProps. These slots are client-side composition: import custom components in a client wrapper rather than passing component functions across the server boundary.

The fallback configuration must be paired with its canonical document route, including /index. FrameSync applies page route/config/edit overrides before paint without replacing the header. Render <FrameSync /> on a missing page to restore the latest namespace fallback. It is harmless outside a frame. Frame fallbacks and page seeds have different lifetimes; do not reseed the persistent frame with fallback data on each render.

Hosts supplying their own composition can use useMosaicStore(seed) and StoreProvider directly. The hook creates one store per instance, keeps its identity across renders, and replaces page data before paint when the seed object identity changes. Omitted fields reset to their defaults; provide a new seed object when refreshing data. The legacy useCreateStore API is unchanged.

Server layouts may import colorModeScript from the pure @jpmorganchase/mosaic-store/theme-preference subpath and render it in an inline head script before hydration. This subpath also exports STORAGE_KEY, parseColorModePreference and serializeColorModePreference. The stored format remains { state: { colorMode: 'light' | 'dark' }, version: 0 }; missing, malformed or blocked storage boots in light mode. The script sets only data-mode; density and other host preferences remain in the host. Continue following your host's script nonce/CSP policy.

Auth.js declaration boundary

The packed consumer checks Mosaic's public declarations with skipLibCheck: false. Its Next hosts use TypeScript 6.0.3 because Next 16.4 currently emits DOM types missing from TypeScript 5.x (upstream issue); Mosaic's library build remains on TypeScript 5.9.

Auth.js 5.0.0-beta.32 currently ships separate declaration defects, including React's removed global JSX namespace and missing internal type exports. The installed-auth runtime fixture therefore mounts the real SessionProvider in a small JavaScript bootstrap, with a separate strict TypeScript contract for Mosaic's public NextAuthAdapter. The browser still verifies authenticated rendering and hydration. This validates Mosaic's declarations and Auth.js runtime integration; it does not certify Auth.js's own declarations or replace them with shims. TypeScript hosts importing SessionProvider directly may encounter those upstream diagnostics until Auth.js fixes them.

Mosaic BETA

Coming soon