Mounting
The committed symlinks under src/app/, src/pages/ and public/ are the
source of truth.
What Next reads is derived from them, and how depends on which router and which command.
The two routers behave differently
next build follows a symlinked directory, so it reads src/app/ as committed
and needs nothing generated. next dev does not — it returns 404 for every
route underneath a symlinked directory. It does follow a symlinked file, so
development gets a tree of real directories with each route file symlinked
individually.
The Pages Router cannot be symlinked at all. Next resolves a route to its
real path, and a Pages Router route reached through a symlink loses track of its
pages/ root. The build then fails looking for /_document while rendering the
404, which is a confusing symptom of a resolution problem. So pages/ is always
materialised as real files.
Strategies
| Strategy | Produces | Used by |
|---|---|---|
source | nothing; Next reads src/app/ | next build |
mirror | app/: real directories, one symlink per file | next dev |
hardlink / copy | app/: duplicated files | filesystems without usable symlinks |
auto, the default, picks source for builds and mirror for next dev.
mirror is preferred over hardlink because a symlink resolves by path rather
than by inode. An editor that saves by writing a new file and renaming it over
the old one breaks a hardlink, leaving the mounted copy serving stale content; a
symlink is unaffected. A watcher re-derives the tree when files are added or
removed, which is all it has to catch.
Assets
public/ needs no derived tree: next dev and next start both serve an app's
assets straight through the committed symlink. Two things do not follow it.
What deploys a build. Vercel's adapter copies each entry of public/ as it
is, so a relative link lands in the build output pointing at nothing — every
asset under it would 404, and Vercel's builder fails on it outright with
Cannot copy '../../id/public' to a subdirectory of itself. So for as long as
next build runs, each app's link is a directory of hard links to the same
files, and the committed link is put back when the build ends — on Ctrl+C and
SIGTERM too, which Next turns into an exit, and when the terminal closes.
Anything that copies public/ after the build — a Dockerfile, say — gets the
links back, so it has to follow them: cp -RL public.
A build killed outright (kill -9, or out of memory) cannot put anything back,
so what it made is recorded first, in
node_modules/.cache/@fairgarden/monolith/. The next next dev, next build
or next start finds the directory there, checks every file in it is one of the
app's, and puts the link back. Anything else in it — a file someone saved there
in the meantime — stops it instead, named, so nothing is deleted to make way.
Only a recorded directory is ever treated like this: the monolith's own assets
can be byte for byte an app's, and a real directory nothing recorded is still
reported as the monolith's.
next dev noticing a new file. It lists public/ when it starts, and its
watcher does not look through a symlinked directory. An asset added to an app
while the dev server runs 404s until it restarts; edits and deletions are picked
up as they happen.
Two consequences worth knowing
Next refuses to run when app and pages live in different folders. An app
with a Pages Router therefore forces the App Router tree to be derived as well,
so source quietly becomes mirror.
And because Next prefers app/ over src/app/ when both exist, a build clears
any app/ left behind by a dev session rather than let it shadow the committed
tree.
Self-reference
Turbopack resolves a mounted file from its real location, so the monolith's
node_modules is not on its lookup path. An app that imports its own modules by
package name — which it should, see Portability — needs
to be able to find itself. withMonolith writes
<app>/node_modules/<package name> pointing at the app, leaving any real
install alone. Pass { selfReference: false } to opt out.
When a module cannot be cloned
A module does not have to come from a submodule. Give an app both a root and a
package, and the checkout is used when its routes are there with the package
as the fallback:
withMonolith(config, {
id: { root: '../id', package: '@fairgarden/id' },
})
An empty directory is what a build host leaves behind when it cannot read a submodule's remote, and that is when the package takes over. A private package installs with a token, which is a credential a build host can be given, whereas a private submodule needs an SSH key it cannot have.
Those files are copied, not linked. Turbopack will not process a route whose
real path is inside node_modules — the build fails with an internal error
about writing an app endpoint, which says nothing about the cause. So a
package-sourced app is materialised outside node_modules automatically, while
path-sourced apps are still symlinked. A committed link that points into
node_modules is skipped for the same reason.
Because such an app has nothing in the committed tree, having one means the derived tree is always built, the same way a Pages Router forces it.