You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 07532e1
Browse filesBrowse the repository at this point in the historyBrowse files
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 graph ID. `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`
Copy file name to clipboardExpand all lines: docs/API.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,7 @@ Builds a single bundle for `entry`, like [`metro build`](./CLI.md#build-entry).
91
91
92
92
-`entry` (string): **Required.** The [entry point](./Concepts.md#entry-point) file to bundle.
93
93
-`platform` (string): The [platform](./Concepts.md#platform) to bundle for (e.g. `'web'`, `'android'`, `'ios'`). Defaults to `'web'`.
94
+
-`environment` (string): The environment to bundle for (e.g. `'react-server'`), equivalent to the bundle URL parameter [`environment`](./GettingStarted.md#bundle). Unset, or `'client'`, for the default (client) environment.
94
95
-`dev` (boolean): Build a development bundle, in which `__DEV__` is `true`. Otherwise, `__DEV__` and `process.env.NODE_ENV` are inlined as `false` and `'production'`. Defaults to `false`.
95
96
-`minify` (boolean): Whether to minify the bundle. Defaults to `true`.
96
97
-`out` (string): Path for the bundle (with `.js` added if missing) and source map (with `.map` extension). Override either path with `bundleOut` or `sourceMapOut`. For example, `out: 'dist/main'` or `out: 'dist/main.js'` with `sourceMap: true` writes `dist/main.js` and `dist/main.map`.
Copy file name to clipboardExpand all lines: docs/GettingStarted.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -178,10 +178,11 @@ Metro can also serve a variant of an asset for a specific [platform](./Concepts.
178
178
179
179
Any JS file in the [project root](./Concepts.md#project-root-and-watch-folders) can be the [entry point](./Concepts.md#entry-point) of a bundle, which includes the file and, recursively, everything it requires. To request a bundle, use the file's path relative to the project root (or [`server.unstable_serverRoot`](./Configuration.md#unstable_serverroot-experimental), if set), with `.js` changed to `.bundle`.
180
180
181
-
Pass build options as query parameters. All are optional. Boolean ones take `true` or `false` and default to `false` unless noted. `dev`, `platform` and `minify` correspond to the bundle's settings of the same name.
181
+
Pass build options as query parameters. All are optional. Boolean ones take `true` or `false` and default to `false` unless noted. `dev`, `platform`, `environment` and `minify` correspond to the bundle's settings of the same name.
182
182
183
183
-`dev`: Build in development mode. Defaults to `true`.
184
184
-`platform`: The [platform](./Concepts.md#platform) requesting the bundle (e.g. `ios`). Defaults to the platform suffix of the requested file name, if any (e.g. `ios` for `index.ios.bundle`).
185
+
-`environment`: The environment to bundle for (e.g. `react-server`), passed to the transformer as `options.environment`, to Babel plugins as `caller.environment` by Metro's Babel transformer, and to the resolver as [`context.environment`](./Resolution.md#environment-string). Unset, empty or `client` for the default (client) environment.
185
186
-`minify`: Minify the code.
186
187
-`excludeSource`: Leave the source code out of the source map, e.g. `/index.map?platform=ios&dev=true&excludeSource=true` returns a source map without `sourcesContent`.
187
188
-`inlineSourceMap`: Append the source map to the bundle as a base64 `data:` URL.
@@ -209,7 +210,7 @@ Required. Transforms a module's code. It receives an object with:
209
210
210
211
-`filename`: The path of the file, relative to the project root.
211
212
-`src`: The source code.
212
-
-`options`: Options for this transformation, e.g. `dev`, `platform`, `minify`, `projectRoot`, `customTransformOptions`and `unstable_transformProfile`.
213
+
-`options`: Options for this transformation, e.g. `dev`, `platform`, `minify`, `projectRoot`, `customTransformOptions`, `unstable_transformProfile`and `environment`.
213
214
-`plugins`: Babel plugins that Metro wants applied to the code.
214
215
215
216
It must return an object with an `ast` key containing the Babel AST of the transformed code, and optionally Babel `metadata`. Metro gets function names for stack traces from `metadata`, so apply the `plugins` it passes in and return the resulting `metadata` to keep them. For example, using Babel:
Copy file name to clipboardExpand all lines: docs/Resolution.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -230,6 +230,10 @@ The set of file extensions used to identify asset files. Defaults to [`resolver.
230
230
231
231
`true` for a development bundle, `false` otherwise.
232
232
233
+
#### `environment: ?string`
234
+
235
+
The environment to bundle for (e.g. `'react-server'`), from the [`environment`](./GettingStarted.md#bundle) bundle option. Absent for the default environment.
@@ -397,7 +401,7 @@ Metro caches and reuses resolver results, which matters mainly for [custom resol
397
401
398
402
1. For given origin module paths _A_ and _B_ and target module name _M_, the resolution for _M_ may be reused if **all** of the following conditions hold:
399
403
1._A_ and _B_ are in the same directory.
400
-
2. The contents of [`dev`](#dev-boolean) and [`customResolverOptions`](#customresolveroptions-string-mixed) are equivalent ( = serialize to JSON the same) in both calls to the resolver.
404
+
2. The contents of [`dev`](#dev-boolean), [`customResolverOptions`](#customresolveroptions-string-mixed) and [`environment`](#environment-string) are equivalent ( = serialize to JSON the same) in both calls to the resolver.
401
405
3. The `platform` is the same in both calls.
402
406
4.[`isESMImport`](#isesmimport-boolean) is the same in both calls.
403
407
2. Any cache of resolutions must be invalidated if any file in the project has changed.
0 commit comments