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 cb928da
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/Bundling.md
+9-2Lines changed: 9 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ id: bundling
3
3
title: Bundling
4
4
---
5
5
6
-
*Bundling* turns your app's source files into a *bundle*: the JavaScript your app loads at runtime. A bundle contains every [module](./Concepts.md#module) reachable from the [entry point](./Concepts.md#entry-point), [transformed](./Concepts.md#transformation) into code the app's JavaScript engine can run, and combined by Metro's [serializer](./Concepts.md#serialization).
6
+
_Bundling_ turns your app's source files into a _bundle_: the JavaScript your app loads at runtime. A bundle contains every [module](./Concepts.md#module) reachable from the [entry point](./Concepts.md#entry-point), [transformed](./Concepts.md#transformation) into code the app's JavaScript engine can run, and combined by Metro's [serializer](./Concepts.md#serialization).
7
7
8
8
## Building a bundle
9
9
@@ -26,6 +26,7 @@ To build a bundle, Metro:
26
26
27
27
Each module's code is wrapped in a function and registered under its numeric ID. For example, an `index.js` that requires `./Button` becomes (simplified, non-dev build):
@@ -45,7 +46,7 @@ Modules refer to each other by numeric IDs assigned at build time, not by path.
45
46
46
47
### Scripts
47
48
48
-
Metro's runtime and the polyfills from [`serializer.getPolyfills`](./Configuration.md#getpolyfills) and [`serializer.polyfillModuleNames`](./Configuration.md#polyfillmodulenames) are transformed as *scripts* instead of modules, and placed at the start of the bundle, before the modules. A script:
49
+
Metro's runtime and the polyfills from [`serializer.getPolyfills`](./Configuration.md#getpolyfills) and [`serializer.polyfillModuleNames`](./Configuration.md#polyfillmodulenames) are transformed as _scripts_ instead of modules, and placed at the start of the bundle, before the modules. A script:
49
50
50
51
- Is wrapped in a function that runs as soon as the bundle loads, with the global object as its `global` argument, instead of in a `__d` call.
51
52
- Is not registered as a module, so it has no module ID and can't be required.
@@ -74,7 +75,9 @@ You only need the formats below if you work with Metro's output directly, e.g. i
74
75
-[RAM bundle](#ram-bundles): RAM (Random Access Modules) bundles store each module separately, so the app can load a module's code only when it's first required.
75
76
76
77
:::note
78
+
77
79
React Native doesn't use RAM bundles with Hermes, its default engine. See [RAM bundles](#ram-bundles).
80
+
78
81
:::
79
82
80
83
### Plain bundle
@@ -83,6 +86,7 @@ The standard format, for environments that expect a single JS file, such as Reac
83
86
84
87
For example, the `index.js` and `Button.js`[above](#modules) become this bundle (simplified, non-dev build):
A RAM bundle stores each module's code separately, either in its own file or at its own offset in a single file. A runtime that parses JavaScript source can then parse only the startup code at launch, and each module when it's first required, instead of the whole bundle. With [inline requires](./Configuration.md#gettransformoptions), a module is required, and so parsed, only when code first uses it, not when a file that imports it loads. This helps when parsing a large bundle slows startup. Metro only writes RAM bundles as build output; the development server doesn't serve them.
107
111
108
112
:::note
113
+
109
114
In React Native, RAM bundles were designed for JavaScriptCore, and aren't used with Hermes, React Native's default engine.
115
+
110
116
:::
111
117
112
118
Hermes runs bytecode compiled at build time, so there's no source to parse at startup, and it memory-maps the bytecode, loading only the parts that run. A plain bundle compiled to Hermes bytecode already gets the benefit a RAM bundle would give. React Native's legacy architecture is also the only one that can load RAM bundles, and React Native doesn't write them by default: its release builds run its `bundle` command, which writes a [plain bundle](#plain-bundle), unless configured to run a different command (`bundleCommand` in the Android Gradle plugin, `BUNDLE_COMMAND` for iOS's `react-native-xcode.sh`).
113
119
114
120
For example, as a [file RAM bundle](#file-ram-bundle), the `index.js` and `Button.js`[above](#modules) become these files (simplified, non-dev build):
115
121
122
+
<!-- prettier-ignore -->
116
123
```js
117
124
// index.android.bundle: the startup code, run when the bundle loads
|`out`|`O`| Output file name (required) | String |
29
-
|`platform`|`p`|[Platform](./Concepts.md#platform) to bundle for (e.g. `web`, `android`, `ios`) | String |
30
-
|`minify`|`z`| Minify the bundle | Boolean |
31
-
|`dev`|`g`| Create a development build, in which `__DEV__` is `true`| Boolean |
32
-
|`config`|`c`| Path to the `metro.config.js` to use | String |
33
-
|`max-workers`|`j`| Number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number |
34
-
|`source-map`|| Generate a source map | Boolean |
35
-
|`source-map-url`|| Source map URL (e.g. `--source-map --source-map-url bundle.map` adds `//# sourceMappingURL=bundle.map` to the bundle) | String |
|`platform`|`p`|[Platform](./Concepts.md#platform) to bundle for (e.g. `web`, `android`, `ios`) | String|
30
+
|`minify`|`z`| Minify the bundle| Boolean |
31
+
|`dev`|`g`| Create a development build, in which `__DEV__` is `true`| Boolean |
32
+
|`config`|`c`| Path to the `metro.config.js` to use | String|
33
+
|`max-workers`|`j`| Number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number|
34
+
|`source-map`|| Generate a source map| Boolean |
35
+
|`source-map-url`|| Source map URL (e.g. `--source-map --source-map-url bundle.map` adds `//# sourceMappingURL=bundle.map` to the bundle) | String|
|`transform-option`|`transformer-option`| Custom transform options as URL-encoded `key=value`. Repeatable (e.g. `--transform-option foo=a%20b` passes `{foo: 'a b'}`) | Array|
38
+
|`reset-cache`||**Deprecated.** Clear Metro's caches before building, like [`resetCache`](./Configuration.md#resetcache)| Boolean |
39
+
|`project-roots`|`P`| Accepted but ignored | Array|
40
+
|`legacy-bundler`|| Accepted but ignored| Boolean |
41
+
|`output-type`|`t`| Accepted but ignored | String|
42
42
43
43
## `serve`
44
44
@@ -52,19 +52,19 @@ npx metro serve --port 8082
52
52
53
53
### Options
54
54
55
-
| Option | Alias|Description | Value |
56
-
|----------|----------|----------|----------|
57
-
|`host`|`h`| Host to listen on. Defaults to `localhost`| String |
58
-
|`port`|`p`| Port to listen on. Defaults to `8081`, overriding [`server.port`](./Configuration.md#port)| Number |
59
-
|`config`|`c`| Path to the `metro.config.js` to use | String |
60
-
|`max-workers`|`j`| Number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number |
61
-
|`secure-server-options`|`s`| HTTPS server options, in dot notation (e.g. `-s.cert="$(cat path/to/cert)" -s.key="$(cat path/to/key)"`) | Object |
62
-
|`secure`||**Deprecated.** Serve over HTTPS. Use `secure-server-options` instead | Boolean |
63
-
|`secure-key`||**Deprecated.** Path to the key file for HTTPS when `secure` is set | String |
64
-
|`secure-cert`||**Deprecated.** Path to the cert file for HTTPS when `secure` is set | String |
65
-
|`reset-cache`||**Deprecated.** Clear Metro's caches on startup, like [`resetCache`](./Configuration.md#resetcache)| Boolean |
66
-
|`project-roots`|`P`| Accepted but ignored | Array |
67
-
|`hmr-enabled`|`hmr`| Accepted but ignored | Boolean |
|`host`|`h`| Host to listen on. Defaults to `localhost`| String|
58
+
|`port`|`p`| Port to listen on. Defaults to `8081`, overriding [`server.port`](./Configuration.md#port)| Number|
59
+
|`config`|`c`| Path to the `metro.config.js` to use | String|
60
+
|`max-workers`|`j`| Number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number|
61
+
|`secure-server-options`|`s`| HTTPS server options, in dot notation (e.g. `-s.cert="$(cat path/to/cert)" -s.key="$(cat path/to/key)"`) | Object|
62
+
|`secure`||**Deprecated.** Serve over HTTPS. Use `secure-server-options` instead| Boolean |
63
+
|`secure-key`||**Deprecated.** Path to the key file for HTTPS when `secure` is set | String|
64
+
|`secure-cert`||**Deprecated.** Path to the cert file for HTTPS when `secure` is set | String|
65
+
|`reset-cache`||**Deprecated.** Clear Metro's caches on startup, like [`resetCache`](./Configuration.md#resetcache)| Boolean |
66
+
|`project-roots`|`P`| Accepted but ignored | Array|
67
+
|`hmr-enabled`|`hmr`| Accepted but ignored| Boolean |
68
68
69
69
## `get-dependencies [entryFile]`
70
70
@@ -79,12 +79,12 @@ Lists all files bundled for a given [entry point](./Concepts.md#entry-point) as
79
79
80
80
### Options
81
81
82
-
| Option | Description | Value |
83
-
|---|---|---|
84
-
|`entry-file`| Absolute path to the root JS file. Or pass it as the first positional argument | String |
85
-
|`output`| Output file name, e.g. `/tmp/dependencies.txt`| String |
86
-
|`platform`|[Platform](./Concepts.md#platform) extension used for selecting modules | String |
87
-
|`transformer`| Custom transformer to use | String |
88
-
|`max-workers`| Maximum number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number |
89
-
|`dev`| If `false`, skip dev-only code paths. Defaults to `true`| Boolean |
90
-
|`verbose`| Enables logging. Defaults to `false`| Boolean |
|`entry-file`| Absolute path to the root JS file. Or pass it as the first positional argument | String|
85
+
|`output`| Output file name, e.g. `/tmp/dependencies.txt`| String|
86
+
|`platform`|[Platform](./Concepts.md#platform) extension used for selecting modules | String|
87
+
|`transformer`| Custom transformer to use | String|
88
+
|`max-workers`| Maximum number of transformer workers. Overrides [`maxWorkers`](./Configuration.md#maxworkers) which defaults to a number based on `os.availableParallelism()`| Number |
89
+
|`dev`| If `false`, skip dev-only code paths. Defaults to `true`| Boolean |
90
+
|`verbose`| Enables logging. Defaults to `false`| Boolean |
0 commit comments