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.
- 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-componentsandmosaic-layoutshave breaking changes, so don't mix old and new versions. - For hosts using Auth.js, install
next-authv5 (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-componentsandmosaic-layoutsnow listnextas a peer dependency. Your site must depend onnextdirectly, which it normally does already.
| Pages Router site | App Router site |
|---|---|
src/pages/_app.tsx | src/app/layout.tsx (HTML shell, fonts, global CSS, site-wide metadata) and src/app/providers.tsx (provider stack) |
src/pages/_document.tsx | src/app/layout.tsx |
src/pages/[...route].tsx | src/app/[namespace]/[...route]/page.tsx |
src/pages/index.tsx (redirect) | src/app/page.tsx |
src/pages/api/auth/[...nextauth].ts | src/auth.ts and src/app/api/auth/[...nextauth]/route.ts |
src/pages/api/content/preview.ts | src/app/[namespace]/[...route]/previewAction.ts (Server Action) |
Browser WebSocket to the CLI's /workflows | src/app/[namespace]/[...route]/persistAction.ts (Server Action) and src/app/api/workflows/[jobId]/events/route.ts |
components object in _app.tsx | src/app/[namespace]/[...route]/MdxComponents.ts |
Metadata component with next/head | generateMetadata in src/app/[namespace]/[...route]/page.tsx |
src/types/mosaic.ts | Removed |
.eslintrc.js | eslint.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/mosaicand 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 isindexas empty, so/mosaic/indexwas served from the/mosaicpage and the header's prefetch of it repeated without end on 404 pagesnot-found.tsx,[namespace]/not-found.tsx,error.tsxandglobal-error.tsxrobots.tsandsitemap.tsapi/revalidate/route.ts, which clears cached content when the CLI reports an updateapi/content/liveandapi/content/ready, which reload pages innext devwhen 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.
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.
_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 bylayout.tsx. It holdsColorModeProviderandThemeProvider, plus the session provider and Mosaic auth adapter when authentication is enabled.NamespaceFrame(src/app/[namespace]/NamespaceFrame.tsx) is mounted by[namespace]/layout.tsxand 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 rootSearchProvider.StoreShell(src/app/providers.tsx) wraps each page and is mounted bypage.tsx. It holds the page's store,BaseUrlProvider,ImageProvider,LinkProviderandLayoutProvider. Layouts leave the header out becauseNamespaceFramerenders 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-fontanddata-action-fonton<html>, with the valuesThemeProviderpasses to Salt. - Use the inline theme script from
src/lib/themePrefScript.ts. It setsdata-modeand 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.
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.
getServerSideProps and the middleware chain (createMiddlewareRunner, middlewarePresets) are gone. Fetch your data in src/app/[namespace]/[...route]/page.tsx instead:
- Write an async function that loads the data. Wrap it in React's
cache()ifgenerateMetadataalso needs it, so it runs once per request. - Call it inside the existing
Promise.allnext toresolveContent. Search is loaded independently by the header through the records API or browser index. - Pass the result to your component as a prop, or add it to
storePropsand read it withuseStorefrom@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.
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/routerwithnext/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.eventsdoesn't exist in the App Router, souseIsLoadingandFadehave 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, useuseIsEditing()from@jpmorganchase/mosaic-content-editor-plugin/useEditMode.
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.
src/app/page.tsx redirects / to /mosaic/index. Change the target to your own namespace.
| Package | Removed | Use instead |
|---|---|---|
mosaic-site-middleware | withMosaicMode, withMDXContent, withSharedConfig, withSearchIndex, withSession, middlewarePresets, createMiddlewareRunner, fromGetServerSidePropsContext | resolveMosaicMode, resolveContent, canonicalRoute, getMdxRaw, getMdxRawSource, getSharedConfig, getTagSuggestions, loadSitemap and serializeMdxForClient. Use auth() from src/auth.ts for the session. |
mosaic-site-components | Body, Document, the OpenAPI MDX component | createMdxRenderer with serializeMdxForClient (see BodyServer.tsx), and src/app/layout.tsx. For OpenAPI, see below. |
mosaic-layouts | useIsLoading, Fade | Nothing. Pass isEditing to LayoutProvider. |
mosaic-content-editor-plugin | useContentEditor, usePageState | EditorProvider and its hooks (usePreviewContent, useSaveState, useErrorMessage, …), and useEditMode, useIsEditing, useEditModeActions |
mosaic-store | SiteState.colorMode, SiteState.actions, registerStore, disposeStore | Mount 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.
src/auth.tsholds the Auth.js configuration, andsrc/app/api/auth/[...nextauth]/route.tsexports its handlers. On the server, callauth()instead ofgetServerSession().- Rename
NEXTAUTH_SECRETtoAUTH_SECRET. The old name still works. Generate a secret withopenssl rand -base64 32. - Remove
NEXTAUTH_URL. The site trusts the request's host instead. - Set
MOSAIC_AUTH_ENABLED=trueto turn sign-in on. GITHUB_ID,GITHUB_SECRETand 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@domainsonly match email addresses that GitHub has verified. If it isn't set, nobody can sign in in production. SetMOSAIC_EDITORS=*to keep the old behaviour, where anyone who could sign in could edit. - In production, the site rejects the placeholder
AUTH_SECRETfrom.env.development. - In
next dev,MOSAIC_DEV_FAKE_AUTH=truesigns you in as a test user without GitHub.
- The editor only appears on pages from a writable source. A source must declare
capabilities: { writable: true }.source-git-repodoes;source-local-folder,source-httpand the other read-only sources don't. If you wrote your own source and want it to be editable, addcapabilitiesto 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_URLwithMOSAIC_WORKFLOWS_URL, which is only read on the server. - Saves no longer use WebSockets. Set
MOSAIC_WORKFLOWS_URLto the CLI's base HTTP URL, such ashttp://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>/eventsroute. An oldws://…/workflowsvalue still works, but logs a warning. - Set
MOSAIC_WORKFLOWS_SECRETto 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=trueshows the editor on every page. It has no effect in production.
| Before | Now | Why |
|---|---|---|
.env.local | .env.development | Next.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.production | Next.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.
| Before | Now |
|---|---|
NEXTAUTH_SECRET | AUTH_SECRET (NEXTAUTH_SECRET still works) |
NEXTAUTH_URL | Remove |
NEXT_PUBLIC_MOSAIC_WORKFLOWS_URL | MOSAIC_WORKFLOWS_URL, plus MOSAIC_WORKFLOWS_SECRET |
NEXT_PUBLIC_MOSAIC_IBCE_PREVIEW_URL | Remove. Preview is a Server Action. |
OPTIMIZE_IMAGES | NEXT_PUBLIC_OPTIMIZE_IMAGES |
MOSAIC_ENABLE_SOURCE_PUSH | Remove. Nothing reads it. |
MOSAIC_S3_* | Remove, with snapshot-s3 mode (see above). |
| Variable | Purpose |
|---|---|
MOSAIC_AUTH_ENABLED | true turns sign-in on. |
MOSAIC_EDITORS | Who may sign in and edit. If it isn't set, nobody can in production. |
MOSAIC_WORKFLOWS_SECRET | Shared secret for saves. Use the same value as the CLI. |
NEXT_PUBLIC_SITE_URL | The site's public URL, used for canonical URLs, sitemap.xml and robots.txt. Set it at build time. |
MOSAIC_REVALIDATE_SECRET | Protects POST /api/revalidate. Use the same value as the CLI. |
MOSAIC_ACTIVE_MODE_CACHE | true 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_CACHE | Only 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.
| Variable | Purpose |
|---|---|
MOSAIC_WORKFLOWS_SECRET | Required for saves. The workflows endpoints (/workflows/jobs) refuse any request without it. |
MOSAIC_WORKFLOWS_TIMEOUT_MS | How long a save may take before it is reported as failed (default 5 minutes). It used to be read by the site. |
MOSAIC_ADMIN_SECRET | Protects 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_ORIGINS | Comma-separated origins allowed to call the CLI from a browser. CORS is now off by default. |
MOSAIC_REVALIDATE_URL, MOSAIC_REVALIDATE_SECRET | When 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_SECRET | Optional. Enables POST /_mosaic_/webhooks/bitbucket, which refreshes git repo sources as soon as Bitbucket reports a push. See Refresh on push. |
- The
/workflowsWebSocket is gone. Saves start withPOST /workflows/jobsand report progress as Server-Sent Events fromGET /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_ORIGINSif a browser calls the CLI directly. - The admin API needs a secret outside development. Only
/_mosaic_/tags/liststays open. If an SSO proxy in front of the CLI uses theAuthorizationheader, send the secret inx-mosaic-admin-secret. mosaic buildempties the snapshot folder (--outjoined with--name) before writing it, so deleted pages no longer linger. It rejects a--namethat points at the output folder itself or outside it, such as.or../x.mosaic uploadis removed, with its-S/--snapshotoption. If you still want a copy of your snapshots in S3, upload the folder yourself, for example withaws 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. RaiserequestTimeoutfor any source that regularly takes longer to respond.
- Docker: the reference Dockerfiles use Node.js 24 and set
MOSAIC_MODE=activein both the build and run stages. Do the same in your own images if they read from a running CLI. They also setMOSAIC_OUTPUT=standalonein the build stage, which makesnext.config.jsemit the.next/standaloneserver they copy into the runtime image. - Network: only the site's server needs to reach the CLI, through
MOSAIC_ACTIVE_MODE_URLandMOSAIC_WORKFLOWS_URL, over plain HTTP. You no longer need to expose the CLI to browsers or allow WebSockets. Proxies must not buffertext/event-streamresponses, 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:filebuilds a fully staticout/folder that any CDN can serve. See Static export. - Security headers: the reference
next.config.jssendsContent-Security-Policy: frame-ancestors 'self'; object-src 'none'; base-uri 'self',X-Frame-Options,X-Content-Type-OptionsandReferrer-Policy, and turns offX-Powered-By. Copy them into your config. A static export ignoresnext.config.jsheaders, so set them in your hosting layer instead. If other sites embed your pages, add their origins toframe-ancestors. - Snapshots: rebuild your snapshots with the new
mosaic build. - Prerender routes: regenerate snapshots to include
mosaic-routes.json. UsegenerateMosaicStaticParams({ pageExtensions: ['.mdx'] })from@jpmorganchase/mosaic-site-middleware/routesinstead of deriving static params fromloadSitemap(). 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.
- Use Node.js 24 or later.
- Upgrade all
@jpmorganchase/mosaic-*packages to the same version. Auth.js hosts also upgradenext-authto v5 and mountNextAuthAdapterinsideSessionProvider. - Export the current
packages/siteusing Create a Site and move your components, layouts, CSS and config into it. - Replace
next/routerimports and movepages/apihandlers toapp/apiroute handlers. - Rename
.env.localto.env.developmentand.env.prodto.env.production, and rename the env vars listed above. - Set
AUTH_SECRET,MOSAIC_AUTH_ENABLEDandMOSAIC_EDITORSon the site. - Set the same
MOSAIC_WORKFLOWS_SECRETon the site and the CLI. - Set
MOSAIC_ADMIN_SECRET, andMOSAIC_CORS_ORIGINSif needed, on the CLI. - Set
MOSAIC_MODE=activeif your site reads from a running CLI, orMOSAIC_MODE=snapshot-fileif it usedsnapshot-s3. - Set
NEXT_PUBLIC_SITE_URLwhen you build the site. - Run
yarn build && yarn start, open a few pages, sign in, then edit and save a page from a Git source.
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.
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.
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.
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.