Skip to content

Commit cb928da

Browse files
authored
Docs: Format the docs with prettier (#2129)
1 parent a87d864 commit cb928da

18 files changed

Lines changed: 880 additions & 267 deletions

‎.github/workflows/build-test-and-deploy.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ jobs:
3535
- run: yarn typecheck
3636
- run: yarn typecheck-ts
3737
- run: yarn lint
38+
- run: yarn lint-markdown
3839
- run: yarn format-check
3940
- run: yarn test-smoke
4041

‎.markdownlint-cli2.jsonc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"config": {
3+
"default": false,
4+
"heading-increment": true,
5+
"no-reversed-links": true,
6+
"no-missing-space-atx": true,
7+
"no-duplicate-heading": {
8+
"siblings_only": true
9+
},
10+
"single-title": true,
11+
"no-trailing-punctuation": true,
12+
"no-space-in-emphasis": true,
13+
"no-space-in-code": true,
14+
"no-space-in-links": true,
15+
"fenced-code-language": true,
16+
"first-line-heading": true,
17+
"no-empty-links": true,
18+
"no-alt-text": true,
19+
"link-fragments": true,
20+
"table-column-count": true
21+
},
22+
"globs": ["docs/*.md"]
23+
}

‎.prettierrc.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,5 +21,12 @@ module.exports = {
2121
parser: 'flow',
2222
},
2323
},
24+
{
25+
files: ['docs/*.md'],
26+
options: {
27+
parser: 'markdown',
28+
requirePragma: false,
29+
},
30+
},
2431
],
2532
};

‎docs/API.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,9 @@ All examples assume `const Metro = require('metro');`.
3737

3838
Metro.loadConfig().then(async config => {
3939
const connectMiddleware = await Metro.createConnectMiddleware(config);
40-
const {server: {port}} = config;
4140

4241
app.use(connectMiddleware.middleware);
43-
server.listen(port);
42+
server.listen(config.server.port);
4443
connectMiddleware.attachHmrServer(server);
4544
});
4645
```

‎docs/Bundling.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ id: bundling
33
title: Bundling
44
---
55

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).
77

88
## Building a bundle
99

@@ -26,6 +26,7 @@ To build a bundle, Metro:
2626

2727
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):
2828

29+
<!-- prettier-ignore -->
2930
```js
3031
// index.js: module ID 0, depends on module 1
3132
__d(function (global, require, _$$_IMPORT_DEFAULT, _$$_IMPORT_ALL, module, exports, _dependencyMap) {
@@ -45,7 +46,7 @@ Modules refer to each other by numeric IDs assigned at build time, not by path.
4546

4647
### Scripts
4748

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:
4950

5051
- 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.
5152
- 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
7475
- [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.
7576

7677
:::note
78+
7779
React Native doesn't use RAM bundles with Hermes, its default engine. See [RAM bundles](#ram-bundles).
80+
7881
:::
7982

8083
### Plain bundle
@@ -83,6 +86,7 @@ The standard format, for environments that expect a single JS file, such as Reac
8386

8487
For example, the `index.js` and `Button.js` [above](#modules) become this bundle (simplified, non-dev build):
8588

89+
<!-- prettier-ignore -->
8690
```js
8791
var __DEV__ = false, process = globalThis.process || {};
8892
(function (global) {
@@ -106,13 +110,16 @@ __r(0);
106110
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.
107111

108112
:::note
113+
109114
In React Native, RAM bundles were designed for JavaScriptCore, and aren't used with Hermes, React Native's default engine.
115+
110116
:::
111117

112118
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`).
113119

114120
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):
115121

122+
<!-- prettier-ignore -->
116123
```js
117124
// index.android.bundle: the startup code, run when the bundle loads
118125
var __DEV__ = false, process = globalThis.process || {};

‎docs/CLI.md‎

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,22 @@ npx metro build index.js --out bundle.js --platform ios
2323

2424
### Options
2525

26-
| Option | Alias | Description | Value |
27-
|----------|----------|----------|----------|
28-
| `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 |
36-
| `resolver-option` | | [Custom resolver options](./Resolution.md#customresolveroptions-string-mixed) as URL-encoded `key=value`. Repeatable (e.g. `--resolver-option foo=bar --resolver-option baz=1` passes `{foo: 'bar', baz: '1'}`) | Array |
37-
| `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 |
26+
| Option | Alias | Description | Value |
27+
| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
28+
| `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 |
36+
| `resolver-option` | | [Custom resolver options](./Resolution.md#customresolveroptions-string-mixed) as URL-encoded `key=value`. Repeatable (e.g. `--resolver-option foo=bar --resolver-option baz=1` passes `{foo: 'bar', baz: '1'}`) | Array |
37+
| `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 |
4242

4343
## `serve`
4444

@@ -52,19 +52,19 @@ npx metro serve --port 8082
5252

5353
### Options
5454

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 |
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 |
6868

6969
## `get-dependencies [entryFile]`
7070

@@ -79,12 +79,12 @@ Lists all files bundled for a given [entry point](./Concepts.md#entry-point) as
7979

8080
### Options
8181

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 |
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 |

0 commit comments

Comments
 (0)