What mounting an app does
A monolith is an ordinary Next app whose route trees are assembled from other apps.
withMonolith does three things when Next loads its config.
It mounts each app
For every app in the map, a symlink is written into the monolith's committed source tree:
src/app/
id/ -> ../../../id/app/
public/
id/ -> ../../id/public/
src/pages/api/
id/ -> ../../../../id/pages/api/
These are committed. They are the readable view of what the monolith is made of — GitHub renders them as links you can follow to the app they point at — and they are the input to everything else. What Next actually reads is derived from them; see Mounting.
It merges each app's config
Each app's own next.config.* is loaded and its rewrites, redirects and
headers are folded into the monolith's, with every path moved under the app's
prefix. Options that the whole deployment shares are checked rather than merged,
so an app that disagrees with the monolith stops the build instead of quietly
losing. See Routing.
It tells each app where it is
Because basePath is not used, nothing prefixes an app's own URLs for it. Each
app is told its mount through the MONOLITH_MOUNTS environment variable, which
mountPrefix and createLink
read. Unset means the app is running on its own, which is the same as being
mounted at the root — so the same code works either way.
MONOLITH_APPS says the same about every app, with the fairgarden part of
its package.json, so apps can find the others they work with and wire
themselves to them: an identity service enrols the apps that declare they sign
in with it, at their mounts on its own origin, and they find it at its mount.
Nobody writes those URLs into the environment, and they follow the deployment
to any domain, a preview's included. Both are fixed at build time, and neither
is a secret.
It checks they can live together
An app that needs a newer Next than the monolith, or a different major, stops the build rather than being miscompiled — see Next versions. So does an app that disagrees about an option the whole deployment shares.
It refuses what it cannot serve
Every app's routes share one tree, so two apps cannot claim the same path. That is checked before anything is mounted — see What a monolith can serve, which also covers giving one app the site root.
What an app has to give up
An app is mounted, not deployed, so anything a deployment only gets one of
belongs to the monolith: proxy/middleware (a locale proxy excepted, which
the monolith's runs for it), instrumentation, pages/_app, pages/_document,
and basePath/distDir. Options like i18n and
trailingSlash have to be identical across every app, because one server serves
all of them.
This is why the monolith is recommended only for core or starter
distributions. A full or enterprise distribution should be separate
deployments. withMonolithicPortability
reports these from inside the app, before anyone tries to mount it.