From 2e9c779cd3e3750cecd91d4323a8277f3d9b94b5 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Wed, 21 Oct 2026 06:23:57 -0700 Subject: [PATCH] Docs: Document the `unstable_*` options users would set Summary: Documents the undocumented `unstable_*` options that make sense for most users to set: - **Config options:** `resolver.unstable_forceFullRefreshPatterns`; `transformer.unstable_allowRequireContext`, `transformer.unstable_workerThreads`; `serializer.unstable_lazilyDefineModules`; `server.unstable_serverRoot`. - **JavaScript API, bundle URL and transformer options:** `unstable_transformProfile`. Internal, niche, deprecated or no-op `unstable_*` options stay undocumented. Changelog: [Internal] Differential Revision: D126045996 --- docs/API.md | 2 +- docs/Configuration.md | 33 +++++++++++++++++++++++++++++++++ docs/GettingStarted.md | 4 +++- 3 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 2979527e7d..0ff2e7b91a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -64,7 +64,7 @@ Creates a Metro server based on the config and returns it. Its `processRequest` **Required options:** `entry` -**Basic options:** `out`, `bundleOut`, `sourceMapOut`, `dev`, `minify`, `platform`, `sourceMap`, `sourceMapUrl`, `assets`, `onBegin`, `onProgress`, `onComplete`, `customResolverOptions`, `customTransformOptions`, `output` +**Basic options:** `out`, `bundleOut`, `sourceMapOut`, `dev`, `minify`, `platform`, `sourceMap`, `sourceMapUrl`, `assets`, `onBegin`, `onProgress`, `onComplete`, `customResolverOptions`, `customTransformOptions`, `unstable_transformProfile`, `output` Bundles `entry` for the given `platform` (defaults to `'web'`). If `out` or `bundleOut` is given, saves the bundle to `bundleOut`, or to `out` with a `.js` extension. If `sourceMap` is set, also generates a source map. The source map will be inlined, unless `sourceMapUrl` is also defined, in which case `sourceMapUrl` is used as the bundle's `sourceMappingURL`. When saving to disk, the source map is also written to `sourceMapOut`, or to `out` with a `.map` extension. If `assets` is `true`, an array of `AssetData` will be generated and returned in the `assets` property of the result object. diff --git a/docs/Configuration.md b/docs/Configuration.md index 512ab382a9..bd9d1e7aa4 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -493,6 +493,14 @@ In a future release of Metro, this option will be removed. ::: +#### `unstable_forceFullRefreshPatterns`
Experimental
+ +Type: `Array` + +Modules that should trigger a full reload instead of a Fast Refresh update when they change, e.g. modules with side effects (such as style registration) that don't re-run correctly when hot reloaded. Patterns are tested against module paths relative to [`projectRoot`](#projectroot). Only applies to development bundles. Defaults to `[]`. + +--- + ### Transformer Options @@ -611,6 +619,18 @@ Type: `string` The URL path prefix written into each asset's `httpServerLocation`, which the app uses to request the asset. Metro's own server only serves assets under `/assets`, so with a different value you need to route those requests yourself, e.g. with [`rewriteRequestUrl`](#rewriterequesturl). Defaults to `'/assets'`. +#### `unstable_allowRequireContext`
Experimental
+ +Type: `boolean` + +Enables `require.context()`, which imports all the files in a directory that match a pattern. Defaults to `false`. + +#### `unstable_workerThreads`
Experimental
+ +Type: `boolean` + +Whether to run transformer workers as worker threads instead of child processes. Defaults to `false`. + #### React Native Only #### `assetPlugins` @@ -736,6 +756,13 @@ Type: `(graph: ReadOnlyGraph, delta: DeltaResult) => mixed` A function called with the dependency graph and the changes since the previous build, each time a graph is built or updated. +#### `unstable_lazilyDefineModules`
Experimental
+ +Type: `boolean` + +Whether the default serializer defines each module lazily, on its first `require`, instead of running every `__d(...)` call at startup. This reduces startup cost and peak memory use for large bundles. Does not affect Fast Refresh updates. Defaults to `false`. + +--- ### Server Options These options are used when Metro serves the content. @@ -746,6 +773,12 @@ Type: `number` Which port to listen on. Defaults to `8081`. +#### `unstable_serverRoot`
Experimental
+ +Type: `?string` + +The directory that bundle URLs and entry files are resolved against, instead of [`projectRoot`](#projectroot). Defaults to `null` (use `projectRoot`). + #### `useGlobalHotkey` Type: `boolean` diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 176c6d08be..8baf01694b 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -145,6 +145,7 @@ Given a configuration and a set of options that you would typically pass to a se * `sourceMap (boolean)`: Whether Metro should generate source maps. * `sourceMapOut (string)`: Where to save the source map, if `sourceMap == true`. No extension will be added. * `sourceMapUrl (string)`: URL where the source map can be found, written as the bundle's `sourceMappingURL`. If `sourceMap` is `true` and `sourceMapUrl` is not set, the source map is inlined into the bundle. +* `unstable_transformProfile ('default' | 'hermes-stable' | 'hermes-canary')`: Passed to the Babel transformer, which can use it to target a specific JavaScript engine. ```js const config = await Metro.loadConfig(); @@ -214,6 +215,7 @@ Any JS file can be used as the root for a bundle request. The file will be looke * `runModule`: whether to end the bundle with the statements that run the entry point. Defaults to `true`. * `shallow`: whether to include only the entry module itself, without its dependencies. Defaults to `false`. * `sourcePaths`: how source files are referenced in the source map: as absolute file paths (`absolute`), or as URL paths on the server (`url-server`). Defaults to `absolute`. +* `unstable_transformProfile`: passed to the Babel transformer (`default`, `hermes-stable` or `hermes-canary`). Defaults to `default`. * `resolver.` and `transform.`: [custom resolver options](./Resolution.md#customresolveroptions-string-mixed) and custom transform options, e.g. `transform.foo=bar` passes `{foo: 'bar'}` to the transformer. For instance, requesting `http://localhost:8081/foo/bar/baz.bundle?dev=true&platform=ios` will create a bundle out of `foo/bar/baz.js` for iOS in development mode. @@ -228,7 +230,7 @@ The JavaScript transformer ([`babelTransformerPath`](./Configuration.md#babeltra ### Method `transform(module)` -Mandatory method that will transform code. The object received has the module's `filename` (relative to the project root), its source code `src`, transformation `options` (e.g. `dev`, `platform`, `minify`, `projectRoot`, `customTransformOptions`), and Babel `plugins` that Metro wants applied. The returned object has to contain an `ast` key that is the AST representation of the transformed code, and may contain the Babel `metadata`. A minimal transformer only parses the code to AST: +Mandatory method that will transform code. The object received has the module's `filename` (relative to the project root), its source code `src`, transformation `options` (e.g. `dev`, `platform`, `minify`, `projectRoot`, `customTransformOptions`, `unstable_transformProfile`), and Babel `plugins` that Metro wants applied. The returned object has to contain an `ast` key that is the AST representation of the transformed code, and may contain the Babel `metadata`. A minimal transformer only parses the code to AST: ```js const babylon = require('@babel/parser');