<aside> ⚠️

This document is shared externally.

</aside>

User Issue: Turbopack refuses to read files outside of the project root. This interferes with various tooling, including the pnpm global store and npm link.

Related GitHub Issues:

• https://github.com/vercel/next.js/issues/93556
• https://github.com/vercel/next.js/issues/91896
• https://github.com/vercel/next.js/pull/92886
• https://github.com/vercel/next.js/issues/84342
• (and many more issues+discussions…)

Why does Turbopack do this?

• Filesystem Watching: We use notify-rs to set up filesystem watchers.
  • On Linux this selectively watches only the files and directories that have previously been read with inotify.
  • Where there are efficient recursive directory watchers on Windows (ReadDirectoryChangesW with bWatchSubtree) and MacOS (FSEvent), it watches the entire project root.
  • If a root directory isn’t explicitly configured, it’s unclear where we should set up a recursive directory watcher. For the project root, we infer the root by looking for a hardcoded list of common package manager lockfiles.
  • Some other JS bundlers simply don’t watch for filesystem changes in these cases, which can lead to “stale cache” bugs (e.g. if you modify an npm linked package without updating the package manager lockfile).
• Cache Portability: We want Turbopack caches to work across multiple machines, with different paths, and potentially even different CPU architectures or operating systems. The most common case here are CI systems where the root path may be randomized.
  • Every file path in Turbopack is represented as a path relative to a virtual file system root.
  • We also use the FileSystem trait to to embed files inside of the Turbopack binary (e.g. for Turbopack’s JavaScript runtime) and to isolate output files from source code to prevent source code from depending on outputs in the .next directory (which could create a cycle and hang the compiler).
  • Here’s a blog post about how Turbopack’s caching layer works (though it doesn’t cover persistent caching): https://nextjs.org/blog/turbopack-incremental-computation

Suggested Solution

• Allow configuring more than one root directory in a Turbopack project.
  • Constraint: Require that the root directories are non-overlapping, otherwise that could lead to ambiguous path resolution logic.
  • Require that directories are given a name. The name is used as an input to DiskFileSystem::new_internal, so it acts as a cache key. The root path on-disk is stored inside of a Vc<_>, so only things reading that root path will be invalidated if the root path changes.
• Make every DiskFileSystem aware of every other DiskFileSystem that is safe to navigate to (everything minus the output filesystem).
  • Store a Vc<DiskFileSystemMap> inside of DiskFileSystem.
    • Hack: This is cyclic, so we’ll have to store this as a RwLock<Vc<DiskFileSystemMap>> or as a turbo_tasks::State<DiskFileSystemMap>
  • Store the list of DiskFileSystems in a PatriciaMap keyed by their canonicalized paths to allow quick lookup.
• Split FileSystemPath::join into separate sync and async APIs
  • Sync API: FileSystemPath::join_child_path
    • Doesn’t have to look up other filesystems, so doesn’t have to read the Vc<DiskFileSystemMap>, returns a FileSystemPath.
    • Only supports child paths, passing any string beginning with "../" generates an error.
    • Prefer calling this API, as it’s more efficient.
  • Async API: FileSystemPath::join_relative_path
    • Is an async #[turbo_tasks::function], takes a non-Vc FileSystemPath as the self argument and returns a Vc<FileSystemPath>
    • Supports arbitrary relative paths, including strings starting with "../"
    • Crossing filesystem boundaries requires reading Vc<DiskFileSystemMap>, so this should automatically invalidate if the map changes.
    • Most calls won’t cross filesystem boundaries, and won’t read any other Vcs, triggering the immutable task optimization in turbo-tasks.
• Include pnpm's default global store path in the default list of filesystem roots.
  • https://pnpm.io/settings#storedir
  • If the user has configured a different storeDir, it’s likely not practical for us to detect this automatically.
• Construct the filesystem watcher lazily, so if an alternate filesystem root is not used it becomes near-zero cost.

Problems this does not solve

• This partially solves the npm link problem, but the user has to manually configure additional roots for Turbopack.
  • In many cases, users are npm linking for temporary local development or debugging, so it should ideally work without much extra configuration.
  • A better solution for this specific use-case would be to allow paths relative to a filesystem root to traverse out of the root [project]/../../other-package/package.json, but to generate some loud warnings when this happens.
  • If we allowed paths relative to the filesystem root that traverse outside of the root, we’d need to figure out how to watch those files. This could likely be solved by using a non-recursive filesystem watcher for these files, at the cost of some performance penalty.
• In some cases, the additional roots may be very large and lead to excessive file watching
  • Watching all of .cache/bazel or .local/share/pnpm/store might be excessively expensive.
  • It might make sense to use the non-recursive filesystem watcher implementation for some of these directories, but this is unclear.