Resolver: Implement VirtualResolution for resolver-provided modules

[robhogan]

Builds on #2041 (VirtualSource) and #2056 (the virtual: namespace). Nothing in Metro produces a virtual module until #2037.

Summary

This implements VirtualResolution: a resolver may return {type: 'virtualModule', virtualPath: ?string, source: string | Buffer}, and Metro bundles the source as a module.

// metro.config.js
const {version} = require('./package.json');

module.exports = {
  resolver: {
    resolveRequest: (context, moduleName, platform) => {
      if (moduleName === 'virtual:build-info') {
        return {
          type: 'virtualModule',
          // One module, shared by every importer
          virtualPath: path.join(__dirname, 'build-info.js'),
          source: `export const version = ${JSON.stringify(version)};`,
        };
      }
      return context.resolveRequest(context, moduleName, platform);
    },
  },
};

Motivation

Worklets

Bundle mode needs each worklet to be a module. Today the Babel plugin writes react-native-worklets/.worklets/<hash>.js from inside the visitor, a resolveRequest maps it back, and a patch makes getOrComputeSha1 return a random SHA-1 for the directory because the file map never saw the file.

No worklet is ever a transform cache hit, and a cache hit on the parent serves a stale generated module. In addition, a race exists where files created at transform time often aren't registered in the file map by the time the resolver looks at the dependencies of the origin module, so the docs recommend patching Metro, falling back to retrying loading several times, to get a successful build.

With virtual modules (as the worklets team have requested before - eg #1605), the worklets plugin emits a specifier carrying the module's source (metro:inline;base64,…, next in #2037) and the resolver answers with a virtual module beside the importing file (App.tsx imports App.inline-<hash>.tsx). Imports inside the worklet resolve as the importer's would, and the cache behaves as it should.

Expo virtual modules

Expo CLI already does something like this by patching Metro: an expoVirtualModules map on bundler._depGraph._fileSystem, getSha1 returning the \0-prefixed id, and a wrapped Bundler.transformFile that reads from the map. It serves \0polyfill:*, \0node:*, \0shim:* and \0weak:*.

Each of those becomes a virtualModule return from resolveRequest, and the transform cache follows the content: a changed EXPO_PUBLIC_* value is a modification of the environment-variables polyfill rather than a stale cache hit, where today its id is constant. Expo still has to trigger re-resolution when the value changes, since nothing on disk does. The difference from worklets is identity - a shim wants one module shared by every importer, which a fixed virtualPath under the project root gives.

Design

What is a virtual module?

A virtual module is a source module like any other - it's a node in the module graph, it may have dependencies, it may have multiple dependants. The difference is it does not exist on disk, so its content and path must come from somewhere else.

In this design, a virtual module's source and virtual path are decided by Metro's resolver, which takes the resolution specifier, origin module path, and the ResolutionContext APIs as usual and produces the source and a virtual path, which is the module's identity, as outputs.

Identity

A virtual path names exactly one module, like a file path. A change in a virtual module's source is a modification of that module rather than a new one, so module ids, HMR updates and DevTools source URLs stay stable across edits. The transform cache key still follows the content, so nothing goes stale.

That puts uniqueness on the resolver: it must give the same source for the same virtual path, and Metro throws if two resolutions in one traversal disagree. A resolver deriving several modules from one file should name them beside it - metro:inline uses App.inline-<hash>.tsx.

Whether an edit is a modification or a new module is up to the resolver's choice of path. metro:inline hashes the source into it, so an edited worklet is a new module, while a fixed path like Expo's keeps one module across changes.

In the graph, a virtual module's path is virtual:<virtualPath>, so it can never collide with a real file, including one it sits beside. The transformer and resolvers see the bare virtual path, so extension checks and relative imports work as they would for a file there. #2056 adds the namespace, and how it appears in development module names and URLs.

Change detection

Metro doesn't watch anything for a virtual module. Its source arrives with a resolution, so it can only change when one of its importers is revisited and its dependencies re-resolved, typically after an edit to the importer. The same source again is a no-op. Different source re-transforms the module and commits it as modified, like an edited file.

So a resolver whose output depends on anything other than the importer, like Expo's environment variables, has to trigger that re-resolution itself.

Visibility in the file map

Virtual modules are not represented in Metro's file map, and therefore not visible through the ResolutionContext APIs like doesFileExist. That's deliberate, and consistent with other bundlers (which follows from their use of real IO for resolution).

An observable consequence of that is that importing a virtual module by its virtual path as if it were a real module will fail, and require.context() won't include it. IMO, that's expected.

If they were represented, one resolution could perform a synchronous doesFileExist on a virtual path, and the result would be sensitive to whether another resolution that creates it has already run. Since traversal order is not deterministic that would make builds non-deterministic.

Nullability of VirtualResolution.virtualPath

This is nullable so that in future a module with no origin/base can be declared - this would be needed for a spec-compliant implementation of a data: URL. It's rejected with an invariant for now, because otherwise the nullability would transfer to ResolutionContext.originModulePath, which would be a breaking change. We don't need data: yet anyway, so we can leave this for later, but my hunch is that all such path-less virtual modules could be content-defined, rather than needing another form of ID.

How it works

In the order the source flows:

1. Resolution - ModuleResolution turns a virtualModule resolution into a BundlerResolution whose filePath is the namespaced path, carrying the source as a Buffer with its SHA-1. A null virtualPath fails an invariant here.
2. Memoisation - DependencyGraph memoises resolutions per origin directory, but a virtual path may depend on the importing file, so virtual resolutions are memoised per origin file. The per-directory memo is checked first, so other resolutions cost no extra lookup.
3. The edge - buildSubgraph puts the source on the dependency edge as a {type: 'buffer', source, sha1} VirtualSource, the shape Graph: Carry require.context inputs as a VirtualSource #2041 gave require.context. It transforms the module, and resolves its dependencies, as the bare virtual path. Two edges giving one virtual path different content is an error, raised outside the optional-dependency try so it can't be swallowed.
4. Transform - getTransformFn hands the buffer to transformFile in place of a file read, as it does a rendered context template, so the cache key follows the content.
5. Change detection - Graph.traverseDependencies revisits an existing virtual module when its edge brings a different SHA-1, commits it as modified, and writes the new source back for later comparisons.

metro-resolver documents and exports the VirtualResolution type.

Changelog: [Feature] Resolver: custom resolvers may return {type: 'virtualModule', virtualPath, source} to provide a module's source directly

Test plan

yarn flow
yarn jest packages/metro/src/DeltaBundler/__tests__/{Graph,buildSubgraph,resolver}-test.js packages/metro/src/integration_tests/__tests__/virtual-module-test.js

New tests:

• Graph-test: a virtual module is added once, under its namespaced path. New source at the same path is a modification of the same module, the same source is not, and the new source sticks for later traversals. Two importers disagreeing is an error, even on an optional dependency.
• resolver-test: resolution to the namespaced path, a Buffer source with the same identity as the same text, and the null invariant.
• buildSubgraph-test: the transformer and the resolver see the bare virtual path.
• virtual-module-test (integration): bundles from a custom resolveRequest and runs the bundle. Covers a relative import from a virtual module, two importers in one directory getting separate modules, require.resolveWeak, a .ts virtual path transformed as TypeScript, dev module names, and a production build.

These pass on Windows 11 too, at the top of the stack.

Verified e2e against this stack with the app at https://github.com/robhogan/metro-x-worklets, and validated with @tjzel.