Repository navigation
Conversation
Frameworks that build React Server Components bundle one project for several environments, such as `react-server` and the client, which need different resolution and transforms. Today they encode the environment in `customTransformOptions` and `customResolverOptions`. That keeps caches apart, but Metro core can't see it, so it can't vary resolution or module IDs by environment. This adds `environment`, a first-class bundle option beside `platform`. An unset or empty environment, or one named `client`, is the default (client) environment. It is set by the `environment=` bundle URL parameter, which lazy split-bundle URLs inherit from their parent, by `runBuild`'s `environment` option, and by `BundleOptions.environment` for `Server.build`. `splitBundleOptions` puts it in both the resolver and the transform options, from which it reaches: - The transform cache key, which also keeps shared transform results apart, and the options custom transformers receive (`options.environment`). `Transformer.transformFile` accepts it as a known transform option. - The Babel caller, as `caller.environment`, when the default `metro-babel-transformer` is used. - The resolution cache key, and `ResolutionContext.environment` for custom resolvers. - Graph IDs, so each environment gets its own graph. Metro doesn't act on the value yet. Per-environment export conditions and an environment-aware module ID factory will build on it. **Compatibility** Every new field is optional, so existing code that builds `BundleOptions`, transform or resolver options, or a `ResolutionContext` is unaffected. With the environment unset, transform cache keys, resolution cache keys, graph IDs and the Babel caller are byte-identical to before: the transform key gains a trailing element, and `getGraphId` and the Babel caller gain a key, only when it is set. Tests pin the unset transform key and check that the unset graph ID has no environment key. `null` and `'client'` are treated as unset. Frameworks that encode the environment in custom options can set `environment` instead. Moving over changes their transform cache keys once. Changelog: [Feature] Add the `environment` bundle option (`environment=` in bundle URLs), passed to transformers as `options.environment`, to Babel as `caller.environment` and to custom resolvers as `context.environment`
robhogan
force-pushed
the
robhogan/bundle-environment
branch
from
November 22, 2026 18:06
07532e1 to
6183125
Compare
environment bundle optionenvironment bundle option
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Frameworks implementing React Server Components must bundle the same project for several "environments" (eg
react-serverand the mobile client), with different resolution and transforms. Currently, Expo puts the environment in its owncustom(Resolver|Transform)Optionsand handles the differences itself.That works for what the framework owns, but custom options are opaque to Metro, so:
browseron web, can't vary by environment.This change
This adds
environmentas a bundle option alongsideplatform, set by theenvironment=URL param,runBuildorBundleOptions.options.environment, Babel plugins ascaller.environment(frommetro-babel-transformer) and custom resolvers ascontext.environment.Metro doesn't act on it yet. Per-environment resolver options and module IDs will build on it, as designed in https://robhogan.github.io/reports/metro-bundle-environments/
Naming
"Environment" is React's word for this split, and Vite, Parcel and Expo use it the same way. The alternatives:
platform(esbuild) andtarget(Bun) name only the runtime. Metro'splatformis taken, andtargetmeans a language level in Babel and TypeScript.runtimecan't tell SSR fromreact-server, which both run on Node but have different roles within the same project.The downside is a clash with
NODE_ENVand Babel'senvName, where "environment" means development vs production. IMO there's no real risk of ambiguity in context.environmentvsplatformPlatform is what a bundle renders for, and environment is where it runs and on which side of the server/client boundary.
react-serverbundle for iOS runs in Node, but still needs.ios.jsfiles andPlatform.OS === 'ios'.unstable_conditionsByPlatform: {web: ['browser']}.browserdescribes the web client's runtime, so web server bundles shouldn't assert it. Moving it to the client environment is breaking, so it's for later.Changelog
An absent or empty environment, or
client, is the default (the client), which keeps this non-breaking. Every new field is optional.Test plan
environmentfrom one server, and checks the Babel caller and what custom resolvers see.splitBundleOptionsandgetGraphIdagainstmainon the same inputs (plain and Expo-style URLs, an emptyenvironment=, andundefined,nullor''passed directly). Resolver keys, transform options and graph IDs match with no environment, and differ with one.