Repository navigation
Share transform results between graphs - #2239
Conversation
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.
76e401e to
c2a9742
Compare
Metro review: Looks goodRisk: medium · Commit: 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
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. |
|
Measured with the
Δ 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 (
At 5 runs, |t| < 2.3 is not significant (p > 0.05). Bundles byte-identical in every run. |
|
Review notes. None of these are correctness bugs in Metro.
The bot review lists 3 and 4 as memory-only; this is the detail behind them. |
|
Just a heads up that I'm making a change here so that this isn't turned off by Claude regarded this as a kind of cache that should be disabled if That also addresses @vzaidman's point 1. |
Fixed now that transform sharing doesn't depend on non-empty
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).
True. I've updated the docblock to be clearer about this. The more surgical fix is for
Good catch, updated the docblock. |
| 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. |
There was a problem hiding this comment.
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
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 eachimport()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
outputanddependenciesbetween all graphs with equal transform options.Impact
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:
mainView)import(), no RNEven 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
Transformerkeeps the latest transform result for each module (file plus transform options) in memory, checked beforecacheStores.DeltaBundlerlooks up just the released paths in the live graphs, andTransformerdrops 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 fromgetDependencies, 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.getSourceis now created outsidetransformFile. 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.outputandTransformResultDependencyare 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-configwill need to opt out for now. Our production tree shaking edits module data in place:reconcileTransformSerializerPluginreplaces output items with their final transform, andtreeShakeSerializerPlugindecrementsimportson dependency data. Both only run underoptimize/usedExports, ie inexpo 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, ourFileStoredeclines to store them and a patch toGraphsends 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: falseto opt out. It's stripped before the transformer config is hashed, so it doesn't change any cache keys.Benchmark
AI-driven. Heap is
heapUsedafter 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/5e68935ddada24ae6b5928340f0ff951mainboardsesh (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.mainMeta 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
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
asyncRoutesout of the dev web HTML's bundle URL, so withweb.output: 'single'the app's async routes only apply inexpo export. The async routes rows addtransform.asyncRoutes=trueby hand.Not yet tested: HMR to a real client, cold start with parallel chunk requests, Windows.