Skip to content

Share transform results between graphs - #2239

Merged
robhogan merged 7 commits into
mainfrom
robhogan/share-transform-results
Nov 17, 2026
Merged

robhogan merged 7 commits into
mainfrom
robhogan/share-transform-results

Conversation

@robhogan

@robhogan robhogan commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Currently, every graph gets its own freshly deserialised copy of each module's transform output from cacheStores. That's fine with one graph per platform, but lazy bundling serves each import() target as a graph of its own, and that graph holds its entire transitive closure - for a lazy route, most of the app. So dev server memory grows with every lazy chunk a session touches, and each new chunk reads its whole closure back out of the cache, which is why lazy requests get slower as well as heavier.

This PR shares one in-memory copy of each module's output and dependencies between all graphs with equal transform options.

Impact

  • Expo web app with async routes (boardsesh, 392 route chunks): the dev server fits in 1.4GB with sharing. Without it, the same session ran a 24GB machine out of memory.
  • The same app as it ships today (82 lazy chunks): -61% dev server heap (512MB -> 202MB), and chunk requests ~6x faster (median 56ms -> 9ms).
  • Mattermost with 20 screens loaded lazily: -88% heap held by graphs (2.2GB -> 263MB), and chunk requests ~2.4x faster.

The cost is per lazy graph, and it's predictable. Without sharing, each chunk's graph takes about 2.5x its dev bundle size in heap, and sharing removes ~95% of that:

Lazy chunk Dev bundle main This PR
Trivial RN screen (only renders a View) 4.9MB 12.3MB 0.8MB
Library behind import(), no RN 143KB (median) 4.4MB 0.55MB
Expo Router route (boardsesh) 21MB (median) ~55MB (estimated from the ratio) 3.6MB
Large screen (Mattermost) ~40MB 102MB 5.3MB

Even a trivial screen holds its own copy of React Native and the renderer, so every RN route saves at least ~11MB per platform, and apps with many RN routes save the most. iOS and Android graphs don't share with each other, so that's per route, per platform.

This is also the real explanation for #1191 and #1355, which we closed as lazy bundling compounding memory use under parallel requests. It's the number of lazy graphs that matters, not concurrency, and #1355's "long loading each import" is the same cost showing up as time.

This change

Transformer keeps the latest transform result for each module (file plus transform options) in memory, checked before cacheStores.

  • No invalidation of its own. Entries use the same content-addressed key as the cache stores, so a hit returns what a store hit for that key would.
  • Managed explicitly, not by the GC. An edit replaces the module's entry. When a graph update releases modules, or a graph ends, DeltaBundler looks up just the released paths in the live graphs, and Transformer drops the entries no graph holds any more. That's one lookup per released path per graph - an edit that releases a module from each of 392 graphs costs ~6ms in total. A graph that's still building doesn't count as holding anything yet, so a release that lands during a build can drop an entry that graph is about to hold. Later graphs then get a second copy of that module, until it changes or that graph ends. Modules that no graph commits, ie from getDependencies, a failed first build or a failed update, aren't released, which keeps prepended scripts shared but can leave the rest held until a later transform of the same module replaces them.
  • Concurrent requests share one read. Requests for a key that's already in flight share its cache read or worker transform.

getSource is now created outside transformFile. Defined inline, it shared a closure context with the new lookup and kept every file's contents alive (+70MB on Mattermost).

Why an opt-out flag

This is non-breaking for consumers that respect Metro's types and cache keys. Module.output and TransformResultDependency are already read-only, Metro never writes to them (the full suite passes with outputs frozen), and every bundle in the benchmarks below is byte-identical with sharing on. Shared objects aren't frozen or copied though, so code that writes to them anyway will now affect every graph holding the same module. And a shared result is reused whenever a module's key is unchanged, even if a cache store declined to store it, so a transform that depends on inputs outside its key, and relies on that to run again, gets its earlier result.

Expo is the one consumer we know of that does either, so @expo/metro-config will need to opt out for now. Our production tree shaking edits module data in place: reconcileTransformSerializerPlugin replaces output items with their final transform, and treeShakeSerializerPlugin decrements imports on dependency data. Both only run under optimize / usedExports, ie in expo export, but an export builds several graphs with equal transform options in one server (eg one per DOM component), so with sharing each graph's tree shaking would leak into the others. In dev, CSS modules depend on Tailwind's inputs, which aren't in their key: with PostCSS configured, our FileStore declines to store them and a patch to Graph sends them back through the transformer on every update, so with sharing, Tailwind's CSS wouldn't update. We can drop the opt-out once those passes copy before writing and CSS modules get a key that changes with Tailwind's inputs. Expo's dev env var serializer and packed source map patch also write to outputs, but idempotently, so they're safe to share - the boardsesh bundles below are byte-identical through Expo's serializers.

So the option is on by default, with transformer.unstable_shareTransformResults: false to opt out. It's stripped before the transformer config is hashed, so it doesn't change any cache keys.

Benchmark

AI-driven. Heap is heapUsed after two forced GCs, measured in the server process.

Mattermost

RN 0.83.9, iOS dev server with watch off, the main bundle and then 20 screens as split-bundle requests, warm FileStore. Three interleaved runs per mode, heap figures identical across runs. Harness: https://gist.github.com/robhogan/5e68935ddada24ae6b5928340f0ff951

main This PR
Heap held by graphs 2,201MB 263MB (-88%)
Heap per chunk graph 102.4MB 5.3MB (-95%)
Median chunk request 331ms 139ms (~2.4x faster)
Main bundle request no measurable difference
Heap after ending every graph 159.7MB 159.8MB
Edit round, all 21 graphs updated (watch mode) ~2.0s ~1.6s
Bundles byte-identical

boardsesh (Expo web)

Expo SDK 58, RN 0.88.1, Expo Router, served by Expo CLI with the app's own metro.config.js. The main bundle and then every lazy chunk URL it names. One run per mode, so the times are indicative.

main This PR
As shipped (82 chunks): dev server heap 512MB 202MB (-61%)
As shipped: heap in chunk graphs 359MB 45MB (-87%)
As shipped: median / total chunk request 56ms / 6.5s 9ms / 2.7s
Async routes (392 chunks): dev server heap out of memory on a 24GB machine 1,427MB
Bundles byte-identical

Meta apps(?)

IIRC, the likes of FB Marketplace and Twilight use lazy bundling aggressively - they'll likely see substantially reduced memory and better server responsiveness from this, but it'd need measuring at Meta.

The win would be observable in a real dev session with Metro after navigating around the app to request multiple lazy routes.

Changelog

 - **[Performance]**: Dev server memory is ~95% lower per lazy-loaded RN route (`import()` or async routes), and lazy bundle requests are ~2-6x faster
 - **[Experimental]**: Share module outputs between graphs with equal transform options, on by default behind `transformer.unstable_shareTransformResults`. Code that writes to module outputs or dependency data, which the types already forbid, can now affect other graphs

Test plan

New unit tests, plus an integration test that builds real graphs with sharing on and off, checks which outputs they share, and checks that ending the last graph holding a module drops its entry.

Mattermost: this PR's files compiled into the app's Metro 0.88.0. Besides the runs above, 10 rounds of watch-mode edits to a module every graph holds, half of them adding or removing an import, then requesting all 21 bundles: every bundle byte-identical to main, with shared entries flat at ~7,320 and heap flat.

boardsesh at boardsesh/boardsesh@544f0bb, with this PR backported to Metro 0.87.1 (Expo SDK 58's pin), dropping only 0.88-only code. Expo CLI 58 leaves asyncRoutes out of the dev web HTML's bundle URL, so with web.output: 'single' the app's async routes only apply in expo export. The async routes rows add transform.asyncRoutes=true by hand.

Not yet tested: HMR to a real client, cold start with parallel chunk requests, Windows.

@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 16, 2026
Currently, every graph gets its own freshly deserialised copy of each module's transform output from `cacheStores`. That's fine with one graph per platform, but lazy bundling serves each `import()` target as a graph of its own, and that graph holds its entire transitive closure - for a lazy route, most of the app. So dev server memory grows with every lazy chunk a session touches, and each new chunk reads its whole closure back out of the cache, which is why lazy requests get slower as well as heavier.

This PR shares one in-memory copy of each module's `output` and `dependencies` between all graphs with equal transform options.

## Impact

- **Expo web app with async routes** (boardsesh, 392 route chunks): the dev server fits in 1.4GB with sharing. Without it, the same session ran a 24GB machine out of memory.
- **The same app as it ships today** (82 lazy chunks): -61% dev server heap (512MB -> 202MB), and chunk requests ~6x faster (median 56ms -> 9ms).
- **Mattermost with 20 screens loaded lazily**: -88% heap held by graphs (2.2GB -> 263MB), and chunk requests ~2.4x faster.

The cost is per lazy graph, and it's predictable. Without sharing, each chunk's graph takes about 2.5x its dev bundle size in heap, and sharing removes ~95% of that:

| Lazy chunk | Dev bundle | `main` | This PR |
|---|---|---|---|
| Trivial RN screen (only renders a `View`) | 4.9MB | 12.3MB | 0.8MB |
| Library behind `import()`, no RN | 143KB (median) | 4.4MB | 0.55MB |
| Expo Router route (boardsesh) | 21MB (median) | ~55MB (estimated from the ratio) | 3.6MB |
| Large screen (Mattermost) | ~40MB | 102MB | 5.3MB |

Even a trivial screen holds its own copy of React Native and the renderer, so every RN route saves at least ~11MB per platform, and apps with many RN routes save the most. iOS and Android graphs don't share with each other, so that's per route, per platform.

This is also the real explanation for #1191 and #1355, which we closed as lazy bundling compounding memory use under parallel requests. It's the number of lazy graphs that matters, not concurrency, and #1355's "long loading each import" is the same cost showing up as time.

## This change

`Transformer` keeps the latest transform result for each module (file plus transform options) in memory, checked before `cacheStores`.

- **No invalidation of its own.** Entries use the same content-addressed key as the cache stores, so they can only be stale where a store hit would be. Sharing is skipped when `cacheStores` is empty, since that disables caching.
- **Managed explicitly, not by the GC.** An edit replaces the module's entry. When a graph update releases modules, or a graph ends, `DeltaBundler` looks up just the released paths in the live graphs, and `Transformer` drops the entries no graph holds any more. That's one lookup per released path per graph - an edit that releases a module from each of 392 graphs costs ~6ms in total - and an entry dropped early only costs a cache store read.
- **Concurrent requests share one read.** Requests for a key that's already in flight share its cache read or worker transform.

`getSource` is now created outside `transformFile`. Defined inline, it shared a closure context with the new lookup and kept every file's contents alive (+70MB on Mattermost).

## Why an opt-out flag

This is non-breaking for consumers that respect Metro's types. `Module.output` and `TransformResultDependency` are already read-only, Metro never writes to them (the full suite passes with outputs frozen), and every bundle in the benchmarks below is byte-identical with sharing on. Shared objects aren't frozen or copied though, so code that writes to them anyway will now affect every graph holding the same module.

Expo is the one consumer we know of that does, so `@expo/metro-config` will need to opt out in the short term. Our production tree shaking edits module data in place: `reconcileTransformSerializerPlugin` replaces output items with their final transform, and `treeShakeSerializerPlugin` decrements `imports` on dependency data. Both only run under `optimize` / `usedExports`, ie in `expo export`, but an export builds several graphs with equal transform options in one server (eg one per DOM component), so with sharing each graph's tree shaking would leak into the others. Once those passes copy before writing, we can drop the opt-out. Expo's dev env var serializer and packed source map patch also write to outputs, but idempotently, so they're safe to share - the boardsesh bundles below are byte-identical through Expo's serializers.

So the option is on by default, with `transformer.unstable_shareTransformResults: false` to opt out. It's stripped before the transformer config is hashed, so it doesn't change any cache keys.

## Benchmark

AI-driven. Heap is `heapUsed` after two forced GCs, measured in the server process.

### Mattermost

RN 0.83.9, iOS dev server with watch off, the main bundle and then 20 screens as split-bundle requests, warm `FileStore`. Three interleaved runs per mode, heap figures identical across runs.

| | `main` | This PR |
|---|---|---|
| Heap held by graphs | 2,201MB | 263MB (-88%) |
| Heap per chunk graph | 102.4MB | 5.3MB (-95%) |
| Median chunk request | 331ms | 139ms (~2.4x faster) |
| Main bundle request | no measurable difference | |
| Heap after ending every graph | 159.7MB | 159.8MB |
| Edit round, all 21 graphs updated (watch mode) | ~2.0s | ~1.6s |
| Bundles | | byte-identical |

### boardsesh (Expo web)

Expo SDK 58, RN 0.88.1, Expo Router, served by Expo CLI with the app's own `metro.config.js`. The main bundle and then every lazy chunk URL it names. One run per mode, so the times are indicative.

| | `main` | This PR |
|---|---|---|
| As shipped (82 chunks): dev server heap | 512MB | 202MB (-61%) |
| As shipped: heap in chunk graphs | 359MB | 45MB (-87%) |
| As shipped: median / total chunk request | 56ms / 6.5s | 9ms / 2.7s |
| Async routes (392 chunks): dev server heap | out of memory on a 24GB machine | 1,427MB |
| Bundles | | byte-identical |

## Changelog

```
 - **[Experimental]**: Share module outputs between graphs with equal transform options, on by default behind `transformer.unstable_shareTransformResults`. This cuts dev server memory by ~60-90% in apps with lazy bundles, and makes lazy chunk requests several times faster. Code that writes to module outputs or dependency data, which the types already forbid, can now affect other graphs
```

## Test plan

New unit tests, plus an integration test that builds real graphs with sharing on and off, checks which outputs they share, and checks that ending the last graph holding a module drops its entry.

Mattermost: this PR's files compiled into the app's Metro 0.88.0. Besides the runs above, 10 rounds of watch-mode edits to a module every graph holds, half of them adding or removing an import, then requesting all 21 bundles: every bundle byte-identical to `main`, with shared entries flat at ~7,320 and heap flat.

boardsesh at boardsesh/boardsesh@544f0bb, with this PR backported to Metro 0.87.1 (Expo SDK 58's pin), dropping only 0.88-only code. Expo CLI 58 leaves `asyncRoutes` out of the dev web HTML's bundle URL, so with `web.output: 'single'` the app's async routes only apply in `expo export`. The async routes rows add `transform.asyncRoutes=true` by hand.

Not yet tested: HMR to a real client, cold start with parallel chunk requests, Windows.
@robhogan
robhogan force-pushed the robhogan/share-transform-results branch from 76e401e to c2a9742 Compare November 16, 2026 22:14
@robhogan
robhogan marked this pull request as ready for review November 16, 2026 22:15
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Metro review: Looks good

Risk: medium · Commit: 2e76f50 · 6 commands run

Graphs with equal transform options now share one in-memory copy of each module's transform output and dependencies. Entries are keyed by the transform cache key and dropped when no live graph holds them any more. Since my last review, released virtual-module paths are mapped to the source paths they were transformed as, so their shared entries are now dropped. A new integration test fails without that change. Tests, typecheck, lint and API snapshots all pass, and I found nothing new that needs changing.

No findings.

Verified
  • ✅ yarn jest --no-watchman packages/metro/src/DeltaBundler packages/metro/src/integration_tests/__tests__/share-transform-results-test.js packages/metro/src/integration_tests/__tests__/build-test.js — 22 suites, 560 tests
  • ✅ Revert paths.map(getModuleSourcePath)topaths in DeltaBundler.js, then run share-transform-results-test.js (failed as expected) — The new virtual-module test fails (expected 6 cache reads, received 5), so it covers the new mapping. The change was reverted afterwards.
  • ✅ yarn jest --no-watchman packages/metro/src/integration_tests packages/metro/src/Server packages/metro/src/IncrementalBundler packages/metro-config — 28 suites, 263 tests
  • ✅ yarn typecheck
  • ✅ yarn eslint <changed metro files>
  • ✅ yarn verify-api-snapshots

Not run: I didn't benchmark head against base. I wrote a script for it (bench/gen.js, run.js, bench.sh: 20 lazy-route graphs over a generated 1,500-module core, warm FileStore, base and head alternated), but the sandbox's permission check denied running it and this session can't approve it. The memory and time claims are backed by a maintainer's interleaved runs in the discussion, and the code changed since my last review only remaps the released paths. I didn't check Windows behavior, since no Windows machine was available. HMR to a real client is also untested.

Automated review by Claude. Advisory only: it never approves or blocks, and a maintainer makes the call.

@huntie huntie left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WOW.

@vzaidman

Copy link
Copy Markdown
Contributor

Measured with the lazy_bundling benchmark from #2242, with this PR's source changes applied as a patch (5 interleaved runs per variant):

Bundle Variant Δ memory Δ time
Internal Meta App, android (20 chunks) unpatched 546.1 ± 2.7 MB 8.99 ± 0.12 s
Internal Meta App, android (20 chunks) this PR -94.14% (546.1 → 32.0 MB, t -407.8) -53.49% (8.99 → 4.18 s, t -84.3)
Mattermost, ios (20 lazy screens) unpatched 2419.9 ± 0.0 MB 19.39 ± 0.80 s
Mattermost, ios (20 lazy screens) this PR -94.94% (2419.9 → 122.4 MB, t -105170.4) -51.17% (19.39 → 9.47 s, t -27.0)

Δ memory: heap the chunk graphs add to the dev server. Δ time: all chunk requests, one at a time. Bundles byte-identical in every run. The server's heap after the main bundle is 6–8 MB higher with this PR (consistent across runs).

Cold builds (bundling_speed, Internal Meta App, android) are unchanged within noise:

Bundle Variant Wall (s) Wall Δ CPU (s) CPU Δ
prod unpatched 108.0 ± 8.9 1488.0 ± 67.0
prod this PR 112.8 ± 17.0 +4.44% (t 0.6) 1490.5 ± 107.1 +0.17% (t 0.0)
dev unpatched 89.2 ± 2.6 1173.8 ± 41.8
dev this PR 91.3 ± 5.2 +2.43% (t 0.8) 1200.4 ± 69.7 +2.26% (t 0.7)

At 5 runs, |t| < 2.3 is not significant (p > 0.05). Bundles byte-identical in every run.

@vzaidman

Copy link
Copy Markdown
Contributor

Review notes. None of these are correctness bugs in Metro.

  1. CI only exercises sharing in the new test. integration_tests/metro.config.js sets cacheStores: [], so sharesTransformResults() is false in every other integration test (build, server, source maps, RAM bundle, require.context, …). A future write to output or dependencies inside Metro would pass CI and only break with sharing on. Could the integration suite also run with a store configured, e.g. one that always misses? I ran it locally that way, with the shared output and dependencies deep-frozen, and every suite that passes on this PR still passes, so nothing in Metro writes to them today.

  2. Optional: freeze shared results behind a debug flag. Deep-freezing what SharedTransformResults stores turns a cross-graph write into a TypeError (in strict-mode code) that names the writer, instead of silently changing other graphs. Not as a default, since Expo's idempotent dev-time writes would throw too, but as an env var or test-only switch it makes finding writers like the tree-shaking passes cheap.

  3. An early drop can leave a duplicate, not only a cache read. A graph that is still building is invisible to heldOutputs: buildSubgraph collects results in moduleData, Graph commits them only after the traversal, and a new graph is registered only after its first build (DeltaBundler.js). If a release of path M lands meanwhile and no other live graph holds its output O, the entry is dropped while the building graph C is about to hold O. The next graph reads a fresh O' from the store and shares it. If C later re-processes M with the same key, Graph.js keeps C's previous module, so C keeps O. The duplicate lasts until M's content changes or C ends. It's bounded and needs concurrency, but "only costs a cache store read" in the description, and "A dropped entry is only a miss" in the docblock, understate it.

  4. Graphs that never register never release their entries. DeltaBundler.getDependencies (getAssets, prepended scripts, getTransformOptions' getDependencies) and a buildGraph whose first traversal throws add entries but never call #notifyModulesReleased. Those entries are dropped only if a live graph later releases the same path. Bounded at one entry per module key, but before this PR those results were collectable once the graph was dropped. Either have getDependencies notify its paths after deltaCalculator.end(), or narrow the docblock ("drops the entries of modules that no graph holds any more") to entries at released paths that no live graph holds.

The bot review lists 3 and 4 as memory-only; this is the detail behind them.

@robhogan

Copy link
Copy Markdown
Collaborator Author

Just a heads up that I'm making a change here so that this isn't turned off by cacheStores: [].

Claude regarded this as a kind of cache that should be disabled if cacheStores: []. I disagree - cache stores are configured stores, they don't preclude internally memory caching. I think it'd be weird if cacheStores: [fileStore] with an empty cache would use less memory (because it surprisingly enables shared transform results) than cacheStores: [].

That also addresses @vzaidman's point 1.

@robhogan

Copy link
Copy Markdown
Collaborator Author

CI only exercises sharing in the new test.

Fixed now that transform sharing doesn't depend on non-empty cacheStores

Optional: freeze shared results behind a debug flag

I like this in principle but I'm just not sure we've got anywhere to put it - it's something like a Metro strict mode (env var?). I'm not sure it's worth adding just for this - Flow/TypeScript already prevents mutating the transform result so I think anyone who's doing it knows they're breaking the rules (ahem, Expo).

An early drop can leave a duplicate, not only a cache read.

True. I've updated the docblock to be clearer about this. The more surgical fix is for DeltaBundler to queue and flush released modules, but that's complicated in itself so I'll leave it out of this PR.

Graphs that never register never release their entries.

Good catch, updated the docblock.

Comment thread packages/metro-config/src/types.js Outdated
transformVariants: {readonly [name: string]: Partial<ExtraTransformOptions>},
publicPath: string,
// Share one in-memory copy of each transform result between graphs with
// equal transform options. Off when `cacheStores` is empty. Experimental.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit · Config type comment still says sharing is off when cacheStores is empty

Commit 9927748 made sharing independent of cacheStores: sharesTransformResults now returns only config.transformer.unstable_shareTransformResults, and there's a new Transformer test for sharing with cacheStores: []. The comment on unstable_shareTransformResults in TransformerConfigT still says "Off when cacheStores is empty". Anyone who reads it and sets cacheStores: [] to turn sharing off would still get sharing. Suggest removing that sentence, which would also match docs/Configuration.md.

Evidence: grep cacheStores on the head: types.js:170 is the only remaining reference to the old gating. Transformer.js sharesTransformResults doesn't read cacheStores, and the test 'with transformer.unstable_shareTransformResults and empty cacheStores, transforms once and shares the result' passes. · id a3f0bb8e

@robhogan
robhogan added this pull request to stack #2245 November 17, 2026 19:13
@robhogan
robhogan merged commit 843f2b0 into main Nov 17, 2026
16 checks passed
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.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants