Skip to main content

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

StrategyProducesUsed by
sourcenothing; Next reads src/app/next build
mirrorapp/: real directories, one symlink per filenext dev
hardlink / copyapp/: duplicated filesfilesystems 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.