Skip to content

Pass the graph's transform options to createModuleId - #2275

Draft
robhogan wants to merge 1 commit into
mainfrom
robhogan/module-id-context
Draft

robhogan wants to merge 1 commit into
mainfrom
robhogan/module-id-context

Conversation

@robhogan

Copy link
Copy Markdown
Collaborator

A module ID factory only sees a module's path, so a server that runs bundles for several platforms or environments in one JS runtime (eg SSR or RSC alongside client bundles) can't give each its own ID space. Expo CLI works around this by patching Server._getSortedModules and copying HmrServer._prepareMessage wholesale, just to pass a second argument through.

This passes the transform options of the module's graph as an optional second argument, {transformOptions}, everywhere Metro serializes a graph: bundles, source maps, /symbolicate, RAM bundles, build() and HMR updates. Server and HmrServer bind it per graph, so serializers (including custom ones) still get a one-argument createModuleId and their calls carry the context for free. Factories that ignore the argument, including the default, are unaffected.

A lazy bundle is a graph of its own, but its URL carries its parent's transform params, so a factory that compares contexts by value gives a module the same ID in both.

Alternatives

  • Graph ID - it includes the entry file, so a lazy chunk would get a different ID space from its parent. Factories would also have to parse a private cache key.
  • The graph itself - same identity problem for lazy chunks, and it invites IDs that depend on graph contents or order. There's no graph at all when a framework needs an ID for a module the target graph doesn't contain yet (eg RSC manifests).
  • A narrower {platform, environment} - every new dimension would need a Metro change, and Expo's real dimensions live in customTransformOptions anyway.
  • Threading the context through SerializerOptions - every serializer would have to forward it, and an existing custom serializer calling createModuleId(path) would silently get unscoped IDs while Metro's own map and symbolication paths got scoped ones.
  • A factory per graph - the default sequential factory would give a lazy chunk IDs that collide with its parent's, and HMR relies on one factory per server.

Compatibility

The bound function always passes Metro's context, so a custom serializer that passed its own second argument (as Expo's does) now reaches the factory with {transformOptions} instead. Expo will need to read context.transformOptions in the same @expo/metro bump. Similarly, a factory typed with an incompatible second parameter no longer type-checks.

Server.getCreateModuleId() still returns the unbound function, and resolver options aren't in the context. The context is an object, so either can follow without breaking anything.

Changelog

 - **[Feature]**: `serializer.createModuleIdFactory`: the returned function receives the module's graph `{transformOptions}` as an optional second argument
 - **[Types]**: Factories typing a different second parameter must accept `ModuleIdContext`

Test plan

New tests in Server-test (bundle, map, /symbolicate, build(), getRamBundleInfo()), HmrServer-test and hmrJSBundle-test, which all fail without the change.

A module ID factory sees only a module's path, so a server that runs bundles for several platforms or environments in one JavaScript environment has no way to give each its own ID space. Expo patches `Server._getSortedModules` and copies `HmrServer._prepareMessage` to pass such a context itself, and its serializer wraps `createModuleId` to do the same.

`createModuleId` now takes an optional second argument, `{transformOptions}`, the transform options of the graph the module belongs to. `Server` and `HmrServer` bind it per graph wherever Metro serializes a graph: bundle, source map, symbolication (exploded maps), `build()`, RAM bundle info and HMR updates. Serializers still receive a one-argument `createModuleId` in their options, and calls to it from Metro's serializers, `helpers/js`, `wrapModule` and custom serializers now carry the context.

**Semantics**

- Factories that ignore the second argument behave exactly as before. The default factory ignores it, so bundles, maps and HMR payloads are unchanged.
- The bound function always passes Metro's context. A custom serializer that called `options.createModuleId(path, ownContext)` used to reach the factory with `ownContext`, and now reaches it with `{transformOptions}`. A factory that read its own context shape from a serializer must read `context.transformOptions` instead (Expo's `createStableModuleIdFactory` is the known case).
- Metro builds a new context object per bind, so a factory must compare contexts by value. A lazily loaded bundle has its parent's transform options, so a value-deterministic factory gives a module the same ID in both.
- `Server.getCreateModuleId()` returns the unbound function. Callers that pass only a path get no context.
- `hmrJSBundle` passes only the path when mapping inverse dependencies. It used `.map(createModuleId)`, which passed the array index as a second argument.

**Types**

`ModuleIdContext` and `CreateModuleIdFn` are exported from `metro` and `metro/private/DeltaBundler/types`, and `serializer.createModuleIdFactory` is typed `() => CreateModuleIdFn`. A one-argument function still satisfies it. A factory whose second parameter has an incompatible type, such as `{platform?: ?string, environment?: ?string}`, no longer type-checks against it.

Changelog: [Feature] `serializer.createModuleIdFactory`: the returned function receives the module's graph transform options as an optional second argument, `{transformOptions}`. [Types] Factories typing a different second parameter must accept `ModuleIdContext`.
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. needs-meta-import

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant