Skip to content

RSC: Add an environment bundle option - #2277

Draft
robhogan wants to merge 1 commit into
mainfrom
robhogan/bundle-environment
Draft

robhogan wants to merge 1 commit into
mainfrom
robhogan/bundle-environment

Conversation

@robhogan

@robhogan robhogan commented Nov 22, 2026 •

Copy link
Copy Markdown
Collaborator

Frameworks implementing React Server Components must bundle the same project for several "environments" (eg react-server and the mobile client), with different resolution and transforms. Currently, Expo puts the environment in its own custom(Resolver|Transform)Options and handles the differences itself.

That works for what the framework owns, but custom options are opaque to Metro, so:

  • Metro's own defaults, like browser on web, can't vary by environment.
  • Config can't declare per-environment resolution.
  • Babel plugins and resolvers that aren't framework-specific have no common name to read.
  • Metro's planned RSC support, which links server and client graphs, can't tell them apart.

This change

This adds environment as a bundle option alongside platform, set by the environment= URL param, runBuild or BundleOptions.

  • Transformers get it as options.environment, Babel plugins as caller.environment (from metro-babel-transformer) and custom resolvers as context.environment.
  • It's part of the transform and resolution cache keys and the graph ID, so each environment gets its own graph.
  • Lazy split bundles inherit it from their parent's URL.

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:

  • Layers (webpack, Rspack) tag individual modules, while this is per bundle.
  • platform (esbuild) and target (Bun) name only the runtime. Metro's platform is taken, and target means a language level in Babel and TypeScript.
  • runtime can't tell SSR from react-server, which both run on Node but have different roles within the same project.

The cost is a clash with NODE_ENV and Babel's envName, where environment means development vs production.

environment vs platform

Platform is what a bundle renders for, and environment is where it runs and on which side of the server/client boundary.

  • They're independent: a react-server bundle for iOS runs in Node, but still needs .ios.js files and Platform.OS === 'ios'.
  • For the client, the platform has mostly implied the runtime (an iOS app, an Android app or a browser page, web workers aside), so Metro has managed with platform alone until now.
  • That breaks down for Metro's default unstable_conditionsByPlatform: {web: ['browser']}. browser describes 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

 - **[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`

An absent or empty environment, or client, is the default (the client), which keeps this non-breaking. Every new field is optional.

Test plan

  • New unit tests, plus an integration test that serves one entry with and without environment from one server, and checks the Babel caller and what custom resolvers see.
  • Compared URL parsing, splitBundleOptions and getGraphId against main on the same inputs (plain and Expo-style URLs, an empty environment=, and undefined, null or '' passed directly). Resolver keys, transform options and graph IDs match with no environment, and differ with one.

@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 22, 2026
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
robhogan force-pushed the robhogan/bundle-environment branch from 07532e1 to 6183125 Compare November 22, 2026 18:06
@robhogan robhogan changed the title Add an environment bundle option RSC: Add an environment bundle option Nov 22, 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