Routing
Each app's rewrites, redirects and headers are merged into the monolith's,
with every source and destination moved under the app's mount.
// in apps/id
{ source: '/oidc/:path*', destination: '/api/oidc/:path*' }
// in the monolith
{ source: '/id/oidc/:path*', destination: '/api/id/oidc/:path*' }
A header's source moves the same way, and so does every path a Link header
names, so a preload still finds what it points at:
// in apps/id
{ source: '/', headers: [{ key: 'Link', value: '</theme.css>; rel=preload; as=style' }] }
// in the monolith
{ source: '/id', headers: [{ key: 'Link', value: '</id/theme.css>; rel=preload; as=style' }] }
Other header values are copied as they are.
Next's own paths (/_next/...) and absolute URLs are left alone. The monolith's
own entries stay ahead of the apps', apps keep the order they were declared in,
and rewrite phases (beforeFiles, afterFiles, fallback) are preserved. A
bare rewrites array is treated as afterFiles, which is what Next does.
API routes move differently
Notice /api/oidc became /api/id/oidc and not /id/api/oidc. Next only
treats files directly under pages/api/ as API routes, so an app's
pages/api mounts at pages/api/<name> — nesting it under the app's mount
would turn the handlers into pages. Paths follow the files.
This applies only to apps that actually have a pages/api. For everything else
/api/... is an App Router route handler and moves under the app's mount like
any other path. prefixPath is the function that
decides.
Config that cannot be merged
Some options describe the whole deployment, so merging them is meaningless.
withMonolith refuses to start when an app disagrees with the monolith about
i18n, trailingSlash, skipTrailingSlashRedirect,
skipMiddlewareUrlNormalize, output or assetPrefix, or when an app sets
basePath or distDir, which only the monolith may set.
Failing is deliberate. Dropping an app's i18n silently would produce a
deployment that half works.
serverExternalPackages is the one list an app may keep, as long as the
monolith carries every entry too. An app that needs a package left unbundled —
the id app's oidc-provider, which relies on its own class names — builds the
same on its own and mounted, and the monolith says which entries it is missing
rather than dropping them:
// apps/monolith/next.config.ts
export default withMonolith(
{ serverExternalPackages: ['oidc-provider'] },
{ id: '@fairgarden/id' }
)
Links are not rewritten
basePath is not used, so an app's own hrefs are not prefixed for it. A
next/link pointing at /settings still points at /settings in the monolith,
where the app lives at /id/settings. Use
createLink, and the no-next-link lint rule to catch
the ones you miss.
This is a real limitation of the monolith: without basePath, a deployment only
works on a wildcard domain or a subdomain.