From 158ae1214f2b19ca1d7d6d82c89d9202fee1ed96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Ribaudo?= Date: Mon, 6 Jan 2020 12:56:39 +0100 Subject: [PATCH 1/5] Unify docs about .mjs, .cjs, .js and .json config files --- docs/cli.md | 4 +- docs/config-files.md | 140 +++++++++--------- docs/configuration.md | 35 +++-- docs/node.md | 2 +- docs/options.md | 38 ++--- docs/plugin-external-helpers.md | 4 +- docs/plugin-minify-builtins.md | 3 +- docs/plugin-minify-constant-folding.md | 4 +- docs/plugin-minify-dead-code-elimination.md | 4 +- docs/plugin-minify-flip-comparisons.md | 4 +- docs/plugin-minify-guarded-expressions.md | 4 +- docs/plugin-minify-infinity.md | 4 +- docs/plugin-minify-mangle-names.md | 4 +- docs/plugin-minify-numeric-literals.md | 4 +- docs/plugin-minify-replace.md | 4 +- docs/plugin-minify-simplify.md | 4 +- docs/plugin-minify-type-constructors.md | 4 +- ...ugin-proposal-async-generator-functions.md | 4 +- docs/plugin-proposal-class-properties.md | 4 +- docs/plugin-proposal-decorators.md | 2 +- docs/plugin-proposal-do-expressions.md | 4 +- docs/plugin-proposal-export-default-from.md | 4 +- docs/plugin-proposal-export-namespace-from.md | 4 +- docs/plugin-proposal-function-bind.md | 4 +- docs/plugin-proposal-function-sent.md | 4 +- docs/plugin-proposal-json-strings.md | 4 +- ...n-proposal-logical-assignment-operators.md | 4 +- ...in-proposal-nullish-coalescing-operator.md | 4 +- docs/plugin-proposal-numeric-separator.md | 8 +- docs/plugin-proposal-object-rest-spread.md | 4 +- .../plugin-proposal-optional-catch-binding.md | 4 +- docs/plugin-proposal-optional-chaining.md | 4 +- docs/plugin-proposal-partial-application.md | 6 +- docs/plugin-proposal-pipeline-operator.md | 4 +- docs/plugin-proposal-private-methods.md | 4 +- docs/plugin-proposal-throw-expressions.md | 4 +- .../plugin-proposal-unicode-property-regex.md | 4 +- docs/plugin-syntax-async-generators.md | 4 +- docs/plugin-syntax-bigint.md | 4 +- docs/plugin-syntax-class-properties.md | 4 +- docs/plugin-syntax-decorators.md | 4 +- docs/plugin-syntax-do-expressions.md | 4 +- docs/plugin-syntax-dynamic-import.md | 4 +- docs/plugin-syntax-export-default-from.md | 4 +- docs/plugin-syntax-export-namespace-from.md | 4 +- docs/plugin-syntax-flow.md | 4 +- docs/plugin-syntax-function-bind.md | 4 +- docs/plugin-syntax-function-sent.md | 4 +- docs/plugin-syntax-import-meta.md | 4 +- docs/plugin-syntax-json-strings.md | 4 +- docs/plugin-syntax-jsx.md | 4 +- ...gin-syntax-logical-assignment-operators.md | 4 +- ...ugin-syntax-nullish-coalescing-operator.md | 4 +- docs/plugin-syntax-numeric-separator.md | 4 +- docs/plugin-syntax-object-rest-spread.md | 4 +- docs/plugin-syntax-optional-catch-binding.md | 4 +- docs/plugin-syntax-optional-chaining.md | 4 +- docs/plugin-syntax-partial-application.md | 4 +- docs/plugin-syntax-pipeline-operator.md | 4 +- docs/plugin-syntax-throw-expressions.md | 4 +- docs/plugin-syntax-top-level-await.md | 4 +- docs/plugin-syntax-typescript.md | 4 +- docs/plugin-transform-arrow-functions.md | 4 +- docs/plugin-transform-async-to-generator.md | 4 +- ...plugin-transform-block-scoped-functions.md | 4 +- docs/plugin-transform-block-scoping.md | 4 +- docs/plugin-transform-classes.md | 4 +- docs/plugin-transform-computed-properties.md | 4 +- docs/plugin-transform-destructuring.md | 4 +- docs/plugin-transform-duplicate-keys.md | 4 +- ...lugin-transform-exponentiation-operator.md | 4 +- docs/plugin-transform-flow-comments.md | 4 +- docs/plugin-transform-flow-strip-types.md | 4 +- docs/plugin-transform-for-of.md | 4 +- docs/plugin-transform-function-name.md | 4 +- ...lugin-transform-inline-consecutive-adds.md | 4 +- ...-transform-inline-environment-variables.md | 4 +- docs/plugin-transform-instanceof.md | 4 +- docs/plugin-transform-jscript.md | 4 +- docs/plugin-transform-literals.md | 4 +- ...in-transform-member-expression-literals.md | 4 +- ...lugin-transform-merge-sibling-variables.md | 4 +- docs/plugin-transform-minify-booleans.md | 4 +- docs/plugin-transform-modules-amd.md | 4 +- docs/plugin-transform-modules-commonjs.md | 4 +- docs/plugin-transform-modules-systemjs.md | 4 +- docs/plugin-transform-modules-umd.md | 4 +- ...-transform-named-capturing-groups-regex.md | 4 +- docs/plugin-transform-new-target.md | 4 +- docs/plugin-transform-node-env-inline.md | 4 +- docs/plugin-transform-object-assign.md | 4 +- ...sform-object-set-prototype-of-to-assign.md | 4 +- docs/plugin-transform-object-super.md | 4 +- docs/plugin-transform-parameters.md | 4 +- docs/plugin-transform-property-literals.md | 4 +- docs/plugin-transform-property-mutators.md | 4 +- docs/plugin-transform-proto-to-assign.md | 4 +- ...lugin-transform-react-constant-elements.md | 4 +- docs/plugin-transform-react-display-name.md | 4 +- .../plugin-transform-react-inline-elements.md | 4 +- docs/plugin-transform-react-jsx-compat.md | 4 +- docs/plugin-transform-react-jsx-self.md | 4 +- docs/plugin-transform-react-jsx-source.md | 4 +- docs/plugin-transform-react-jsx.md | 4 +- docs/plugin-transform-regenerator.md | 2 +- docs/plugin-transform-regexp-constructors.md | 4 +- docs/plugin-transform-remove-console.md | 4 +- docs/plugin-transform-remove-debugger.md | 4 +- docs/plugin-transform-remove-undefined.md | 4 +- docs/plugin-transform-reserved-words.md | 4 +- docs/plugin-transform-runtime.md | 4 +- docs/plugin-transform-shorthand-properties.md | 4 +- ...transform-simplify-comparison-operators.md | 4 +- docs/plugin-transform-spread.md | 4 +- docs/plugin-transform-sticky-regex.md | 4 +- docs/plugin-transform-strict-mode.md | 4 +- docs/plugin-transform-template-literals.md | 4 +- docs/plugin-transform-typeof-symbol.md | 4 +- docs/plugin-transform-typescript.md | 6 +- docs/plugin-transform-undefined-to-void.md | 4 +- docs/plugin-transform-unicode-regex.md | 4 +- docs/preset-es2015.md | 4 +- docs/preset-es2016.md | 4 +- docs/preset-es2017.md | 4 +- docs/preset-flow.md | 4 +- docs/preset-minify.md | 4 +- docs/preset-react.md | 4 +- docs/preset-stage-0.md | 4 +- docs/preset-stage-1.md | 4 +- docs/preset-stage-2.md | 4 +- docs/preset-stage-3.md | 4 +- docs/preset-typescript.md | 3 +- docs/usage.md | 74 ++++----- 133 files changed, 282 insertions(+), 521 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 94fd38b0b6..8133855eb3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -137,9 +137,9 @@ Use the `--presets` option to specify presets to use in compilation npx babel script.js --out-file script-compiled.js --presets=@babel/preset-env,@babel/flow ``` -### Ignoring .babelrc +### Ignoring .babelrc.* -Ignore the configuration from the project's `.babelrc` file and use the cli options e.g. for a custom build +Ignore the configuration from the project's `.babelrc.*` file and use the cli options e.g. for a custom build ```sh npx babel --no-babelrc script.js --out-file script-compiled.js --presets=es2015,react diff --git a/docs/config-files.md b/docs/config-files.md index 3a1c260db3..d469a9cf31 100644 --- a/docs/config-files.md +++ b/docs/config-files.md @@ -9,15 +9,15 @@ Babel has two parallel config file formats, which can be used together, or indep * Project-wide configuration * File-relative configuration - * `.babelrc` (and `.babelrc.js` or `.babelrc.cjs`) files + * `.babelrc.*` files * `package.json` files with a `"babel"` key - ## Project-wide configuration New in Babel 7.x, Babel has a concept of a ["root"](options.md#root) directory, which defaults to the current working directory. For project-wide configuration, Babel will automatically search -for a `"babel.config.js"`, `"babel.config.cjs"` or `"babel.config.json"` in this root directory. Alternatively, users can use an explicit +for a `babel.config.*` file, using one of the [supported extensions](#supported-file-extensions), +in this root directory. Alternatively, users can use an explicit ["configFile"](options.md#configfile) value to override the default config file search behavior. Because project-wide config files are separated from the physical location of the config @@ -31,20 +31,9 @@ See the [monorepo](#monorepos) documentation for examples of how to use config f Project-wide configs can also be disabled by setting ["configFile"](options.md#configfile) to `false`. -### `babel.config.js` vs `babel.config.cjs` vs `babel.config.json` - -In general, you should choose JSON over JS wherever possible. JS config files are nice sometimes if you have -complex configuration that is conditional or otherwise computed at build time. However, the downside is that -JS configs are less statically analyzable, and therefore have negative effects on cacheability, linting, -IDE autocomplete, etc. Since `babel.config.json` is a static JSON file, it allows other tools that use Babel -such as bundlers to cache the results of Babel safely, which can be a huge build performance win. - -If you need a JavaScript configuration file, you have two options: `babel.config.js` or `babel.config.cjs`. -They are almost equivalent, except when your `package.json` file contains the [`"type": "module"`](https://nodejs.org/api/esm.html#esm_code_package_json_code_code_type_code_field) option: since Babel configuration files must be scripts and not modules, in this case you must use `babel.config.cjs`. - ## File-relative configuration -Babel loads `.babelrc` (and `.babelrc.js` / `.babelrc.cjs` / `package.json#babel`) files by searching up the +Babel loads `.babelrc.*` files, using one of the [supported extensions](#supported-file-extensions), by searching up the directory structure starting from the ["filename"](options.md#filename) being compiled (limited by the caveats below). This can be powerful because it allows you to create independent configurations for subsections of a package. File-relative configurations are also [merged](options.md#merging) over top of @@ -58,12 +47,12 @@ There are a few edge cases to consider when using a file-relative config: ["babelrcRoots"](options.md#babelrcroots) packages, or else searching will be skipped entirely. These caveats mean that: -* `.babelrc` files _only_ apply to files within their own package -* `.babelrc` files in packages that aren't Babel's 'root' are ignored unless you opt in +* `.babelrc.*` files _only_ apply to files within their own package +* `.babelrc.*` files in packages that aren't Babel's 'root' are ignored unless you opt in with ["babelrcRoots"](options.md#babelrcroots). See the [monorepo](#monorepos) documentation for more discussion on how to configure monorepos that have many packages. - + (and `.babelrc.js` / `.babelrc.cjs` / `package.json#babel`) File-relative configs can also be disabled by setting ["babelrc"](options.md#babelrc) to `false`. ### 6.x vs 7.x `.babelrc` loading @@ -99,10 +88,46 @@ Unfortunately, this approach can be a bit repetitive, and depending on how Babel could require setting ["babelrcRoots"](options.md#babelrcroots). Given that, it may be more desirable to rename the `.babelrc` to be a -[project-wide "babel.config.js"](#project-wide-configuration). As mentioned in the project-wide +[project-wide "babel.config.*"](#project-wide-configuration). As mentioned in the project-wide section above, this may then require explicitly setting ["configFile"](options.md#configfile) since Babel will not find the config file if the working directory isn't correct. +## Supported file extensions + +Babel can be configured using any file extension natively supported by Node.js: you can use `.json`, +`.js`, `.cjs` and `.mjs`, both for `babel.config.*` and `.babelrc.*` files. + +- `babel.config.json` and `.babelrc.json` are parsed as JSON5 and should contain an object matching + the [options](options.md) format that Babel accepts. + + It is recommended to choose this file type wherever possible: JS config files are + handy if you have complex configuration that is conditional or otherwise computed at build time. + However, the downside is that JS configs are less statically analyzable, and therefore have + negative effects on cacheability, linting, IDE autocomplete, etc. + Since `babel.config.json` and `.babelrc.json` are static JSON files, it allows other tools that + use Babel such as bundlers to cache the results of Babel safely, which can be a huge build + performance win. + +- `babel.config.cjs` and `.babelrc.cjs` allow you to define your configuration as CommonJS, + using `module.exports`. + +- `babel.config.mjs` and `.babelrc.mjs` use native ECMAScript modules. They are only supported by + Node.js 13.2 or newer, and might work in older versions when passing `--experimental-modules` flag + to Node.js. + Please remember that native ECMAScript modules are asynchronous (that's why `import()` always + returns a promise!): for this reason, `.mjs` config files will throw when calling Babel + synchronously. + +- `babel.config.js` and `.babelrc.js` behave like the `.mjs` equivalents when your `package.json` + file contains the [`"type": "module"`](https://nodejs.org/api/esm.html#esm_code_package_json_code_code_type_code_field) + option, otherwise they are exactly the same as the `.cjs` files. + +JavaScript configuration files can either export an object, or a function that when called will +return the generated configuration. +Function-returning configs are given a few special powers because they can access an API exposed +by Babel itself. See [Config Function API](#config-function-api) for more information. + +> For compatibility reasons, you could find `.babelrc` used as an alias for `.babelrc.json`. ## Monorepos @@ -115,28 +140,26 @@ With monorepo setups, the core thing to understand is that Babel treats your wor as its logical ["root"](options.md#root), which causes problems if you want to run Babel tools within a specific sub-package without having Babel apply to the repo as a whole. -Separately, it is also important to decide if you want to use [`.babelrc`](#file-relative-configuration) -files or just a central [`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) or -[`babel.config.json`](#project-wide-configuration). [`.babelrc`](#file-relative-configuration) +Separately, it is also important to decide if you want to use [`.babelrc.*`](#file-relative-configuration) +files or just a central [`babel.config.*`](#project-wide-configuration). [`.babelrc.*`](#file-relative-configuration) files are not required for subfolder-specific configuration like they were in Babel 6, so often -they are not needed in Babel 7, in favor of [`babel.config.js`](#project-wide-configuration) (or with the `.cjs` and `.json` extensions). +they are not needed in Babel 7, in favor of [`babel.config.*`](#project-wide-configuration). -### Root `babel.config.js`, `babel.config.cjs` and `babel.config.json` files +### Root `babel.config.*` file -The first step in any monorepo structure should be to create a -[`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) or [`babel.config.json`](#project-wide-configuration) +The first step in any monorepo structure should be to create a [`babel.config.*`](#project-wide-configuration) file in repository root. This establishes Babel's core concept of the base directory of your repository. -Even if you want to use [`.babelrc`](#file-relative-configuration) files to configure each separate package, +Even if you want to use [`.babelrc.*`](#file-relative-configuration) files to configure each separate package, it is important to have as a place for repo-level options. -You can often place all of your repo configuration in the root [`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) -or [`babel.config.json`](#project-wide-configuration). With ["overrides"](options.md#overrides), you can easily +You can often place all of your repo configuration in the root [`babel.config.*`](#project-wide-configuration). +With ["overrides"](options.md#overrides), you can easily specify configuration that only applies to certain subfolders of your repository, which can often be easier to -follow than creating many `.babelrc` files across the repo. +follow than creating many `.babelrc.*` files across the repo. -The first issue you'll likely run into is that by default, Babel expects to load [`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) and [`babel.config.json`](#project-wide-configuration) +The first issue you'll likely run into is that by default, Babel expects to load [`babel.config.*`](#project-wide-configuration) files from the directory set as its ["root"](options.md#root), which means that if you create -a [`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) or [`babel.config.json`](#project-wide-configuration), but run +a [`babel.config.*`](#project-wide-configuration), but run Babel inside an individual package, e.g. ```bash @@ -144,19 +167,17 @@ cd packages/some-package; babel src -d dist ``` the ["root"](options.md#root) Babel is using in that context is _not_ your monorepo root, -and it won't be able to find the [`babel.config.js`](#project-wide-configuration) or -[`babel.config.json`](#project-wide-configuration) file. +and it won't be able to find the [`babel.config.*`](#project-wide-configuration) file. If all of your build scripts run relative to your repository root, things should already work, but if you are running your Babel compilation process from within a subpackage, you need to tell Babel where to look for the config. There are a few ways to do that, but the recommended way is the ["rootMode"](options.md#rootmode) option with `"upward"`, which will make Babel search from -the working directory upward looking for your [`babel.config.js`](#project-wide-configuration), [`babel.config.cjs`](#project-wide-configuration) or -[`babel.config.json`](#project-wide-configuration) file, +the working directory upward looking for your [`babel.config.*`](#project-wide-configuration) file, and will use its location as the ["root"](options.md#root) value. One helpful way to test if your config is being detected is to place a `console.log()` call -inside of it if it is a `babel.config.js` file. Since it is a JS file, the log will execute +inside of it if it is a [`babel.config.*`](#project-wide-configuration) JavaScript file: the log will execute the first time Babel loads it. How you set this value varies by project, but here are a few examples: @@ -211,14 +232,14 @@ There are tons of tools, but at the core of it is that they need the `rootMode` if the working directory is not already the monorepo root. -### Subpackage `.babelrc` files +### Subpackage `.babelrc.*` files -Similar to the the way `babel.config.js`, `babel.config.cjs` and `babel.config.json` files are required to be in the ["root"](options.md#root), -`.babelrc` files must be in the root _package_, by default. This means that, the same way the -working directory affects `babel.config.js`, `babel.config.cjs` and `babel.config.json` loading, it also affects `.babelrc` loading. +Similar to the the way [`babel.config.*`](#project-wide-configuration) files are required to be in the ["root"](options.md#root), +[`.babelrc.*`](#file-relative-configuration) files must be in the root _package_, by default. This means that, the same way the +working directory affects [`babel.config.*`](#project-wide-configuration) loading, it also affects [`.babelrc.*`](#file-relative-configuration) loading. -Assuming you've already gotten your `babel.config.js`, `babel.config.cjs` or `babel.config.json` file loaded properly as discussed above, -Babel will only process `.babelrc` files inside that root package (and not subpackages), +Assuming you've already gotten your [`babel.config.*`](#project-wide-configuration) file loaded properly as discussed above, +Babel will only process [`.babelrc.*`](#file-relative-configuration) files inside that root package (and not subpackages), so given for instance ```text @@ -227,14 +248,14 @@ babel.config.js packages/ mod/ package.json - .babelrc + .babelrc.json index.js ``` -compiling the `packages/mod/index.js` file will not load `packages/mod/.babelrc` because -this `.babelrc` is within a sub-package, not the root package. +compiling the `packages/mod/index.js` file will not load `packages/mod/.babelrc.json` because +this [`.babelrc.*`](#file-relative-configuration) is within a sub-package, not the root package. -To enable processing of that `.babelrc`, you will want to use the ["babelrcRoots"](options.md#babelrcroots) -option from inside your `babel.config.js`, `babel.config.cjs` or `babel.config.json` file to do +To enable processing of that [`.babelrc.*`](#file-relative-configuration), you will want to use the ["babelrcRoots"](options.md#babelrcroots) +option from inside your [`babel.config.*`](#project-wide-configuration) file to do ```js babelrcRoots: [ @@ -242,30 +263,9 @@ babelrcRoots: [ "packages/*", ], ``` -so that Babel will consider all `packages/*` packages as allowed to load `.babelrc` files, +so that Babel will consider all `packages/*` packages as allowed to load [`.babelrc.*`](#file-relative-configuration) files, along with the original repo root. - -## Config Format - -The format of individual config files themselves separates into JS files vs [JSON5](https://json5.org/) files. - -### JSON5 - -Any file that isn't a `.js` or `.cjs` file will be parsed as JSON5 and should contain an object matching -the [options](options.md) format that Babel accepts. - -### JavaScript - -Any `.js` and `.cjs` file will be `require()`ed and should export either a configuration object, or a function -that will return a configuration object when called. The main benefit being that users can include -JS logic to build up their config structures, potentially allowing config logic to be shared -more easily. `.js` files can be used as [project-wide configuration](#project-wide-configuration) or -via `.babelrc.js` (and `.babelrc.cjs`) files for [file-relative configuration](#file-relative-configuration). - -Function-returning configs are given a few special powers because they can access an API exposed -by Babel itself. See [Config Function API](#config-function-api) for more information. - ## Config Function API JS config files may export a function that will be passed config function API: diff --git a/docs/configuration.md b/docs/configuration.md index 1a39bfdafd..5d1694cd8a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -9,22 +9,29 @@ All Babel API [options](options.md) are allowed. However, if the option requires ## What's your use case? -- You want to programmatically create the configuration? +- You are using a monorepo? - You want to compile `node_modules`? -> [`babel.config.js`](#babelconfigjs) is for you! +> [`babel.config.*`](#babelconfigjs) is for you! -- You have a static configuration that only applies to your simple single package? +- You have a configuration that only applies to a single part of your project? -> [`.babelrc`](#babelrc) is for you! +> [`.babelrc.*`](#babelrc) is for you! - Guy Fieri is your hero? -> We recommend using the [`babel.config.js`](config-files.md#project-wide-configuration) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js). +> We recommend using the [`babel.config.*`](config-files.md#project-wide-configuration) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js). -## `babel.config.js` +### `babel.config.json` -Create a file called `babel.config.js` with the following content at the root of your project (where the `package.json` is). +Create a file called `babel.config.json` with the following content at the root of your project (where the `package.json` is). + +```json +{ + "presets": [...], + "plugins": [...] +} +``` ```js module.exports = function (api) { @@ -40,11 +47,11 @@ module.exports = function (api) { } ``` -Check out the [`babel.config.js` documentation](config-files.md#project-wide-configuration) to see more configuration options. +Check out the [`babel.config.*` documentation](config-files.md#project-wide-configuration) to see more configuration options. -## `.babelrc` +### `.babelrc.json` -Create a file called `.babelrc` with the following content in your project. +Create a file called `.babelrc.json` with the following content in your project. ```json { @@ -57,7 +64,7 @@ Check out the [.babelrc documentation](config-files.md#file-relative-configurati ### `package.json` -Alternatively, you can choose to specify your [`.babelrc`](#babelrc) config from within `package.json` using the `babel` key like so: +Alternatively, you can choose to specify your [`.babelrc.json`](#babelrc) config from within `package.json` using the `babel` key like so: ```json { @@ -70,9 +77,9 @@ Alternatively, you can choose to specify your [`.babelrc`](#babelrc) config from } ``` -### `.babelrc.js` +### JavaScript configuratino files -The configuration is the same as [`.babelrc`](#babelrc), but you can write it using JavaScript. +You can also write `babel.config.json` and `.babelrc.json` files using JavaScript: ```js const presets = [ ... ]; @@ -94,6 +101,8 @@ if (process.env["ENV"] === "prod") { module.exports = { presets, plugins }; ``` +You can read more about JavaScript configuration files in the [dedicated documentation](config-files.md) + ## Using the CLI (`@babel/cli`) ```sh diff --git a/docs/node.md b/docs/node.md index 004e068a7d..289a953c69 100644 --- a/docs/node.md +++ b/docs/node.md @@ -84,6 +84,6 @@ npx babel-node --debug --presets es2015 -- script.js --debug | `-x, --extensions` | `".js",".jsx",".es6",".es"` | List of extensions to hook into | | `--presets` | `[]` | Comma-separated list of [presets](presets.md) (a set of plugins) to load and use. | | `--plugins` | `[]` | Comma-separated list of [plugins](plugins.md) to load and use. | -| `--config-file [path]` | `[]` | Path to the babel config file to use. Defaults to working directory babel.config.js | +| `--config-file [path]` | `[]` | Path to the babel config file to use. Defaults to working directory babel.config.* | | `--env-name [name]` | `[]` | The name of the 'env' to use when loading configs and plugins. Defaults to the value of BABEL_ENV, or else NODE_ENV, or else 'development'. | diff --git a/docs/options.md b/docs/options.md index 76b4900dc5..8659ed876e 100644 --- a/docs/options.md +++ b/docs/options.md @@ -71,7 +71,7 @@ The three primary cases users could run into are: * The filename is exposed to plugins. Some plugins may require the presence of the filename. * Options like [`"test"`](#test), [`"exclude"`](#exclude), and [`"ignore"`](#ignore) require the filename for string/RegExp matching. -* `.babelrc` files are loaded relative to the file being compiled. If this option is omitted, Babel will behave as if `babelrc: false` has been set. +* `.babelrc.*` files are loaded relative to the file being compiled. If this option is omitted, Babel will behave as if `babelrc: false` has been set. ### `filenameRelative` @@ -158,25 +158,25 @@ Babel can process the [`"root"`](#root) value to get the final project root. * `"root"` - Passes the [`"root"`](#root) value through as unchanged. * `"upward"` - Walks upward from the [`"root"`](#root) directory, looking - for a directory containing a [`babel.config.js`](config-files.md#project-wide-configuration) - file, and throws an error if a [`babel.config.js`](config-files.md#project-wide-configuration) + for a directory containing a [`babel.config.*`](config-files.md#project-wide-configuration) + file, and throws an error if a [`babel.config.*`](config-files.md#project-wide-configuration) is not found. * `"upward-optional"` - Walk upward from the [`"root"`](#root) directory, - looking for a directory containing a [`babel.config.js`](config-files.md#project-wide-configuration) - file, and falls back to [`"root"`](#root) if a [`babel.config.js`](config-files.md#project-wide-configuration) + looking for a directory containing a [`babel.config.*`](config-files.md#project-wide-configuration) + file, and falls back to [`"root"`](#root) if a [`babel.config.*`](config-files.md#project-wide-configuration) is not found. `"root"` is the default mode because it avoids the risk that Babel will -accidentally load a `babel.config.js` that is entirely outside of the current +accidentally load a `babel.config.*` that is entirely outside of the current project folder. If you use `"upward-optional"`, be aware that it will walk up the directory structure all the way to the filesystem root, and it is always -possible that someone will have a forgotten `babel.config.js` in their home +possible that someone will have a forgotten `babel.config.*` in their home directory, which could cause unexpected errors in your builds. Users with monorepo project structures that run builds/tests on a per-package basis -may well want to use `"upward"` since monorepos often have a [`babel.config.js`](config-files.md#project-wide-configuration) +may well want to use `"upward"` since monorepos often have a [`babel.config.*`](config-files.md#project-wide-configuration) in the project root. Running Babel in a monorepo subdirectory without `"upward"`, -will cause Babel to skip loading any [`babel.config.js`](config-files.md#project-wide-configuration) +will cause Babel to skip loading any [`babel.config.*`](config-files.md#project-wide-configuration) files in the project root, which can lead to unexpected errors and compilation failure. @@ -195,15 +195,15 @@ available inside configuration functions, plugins, and presets, via the ### `configFile` Type: `string | boolean`
-Default: `path.resolve(opts.root, "babel.config.js")`, if it exists, `false` otherwise
+Default: `path.resolve(opts.root, "babel.config.*")`, if it exists, `false` otherwise
Placement: Only allowed in Babel's programmatic options
-Defaults to searching for a default `babel.config.js` file, but can be passed +Defaults to searching for a default `babel.config.*` file, but can be passed the path of any JS or JSON5 config file. -NOTE: This option does _not_ affect loading of [`.babelrc`](config-files.md#file-relative-configuration) files, so while -it may be tempting to do `configFile: "./foo/.babelrc"`, it is not recommended. -If the given [`.babelrc`](config-files.md#file-relative-configuration) is loaded via the standard +NOTE: This option does _not_ affect loading of [`.babelrc.*`](config-files.md#file-relative-configuration) files, so while +it may be tempting to do `configFile: "./foo/.babelrc.json"`, it is not recommended. +If the given [`.babelrc.*`](config-files.md#file-relative-configuration) is loaded via the standard file-relative logic, you'll end up loading the same config file twice, merging it with itself. If you are linking a specific config file, it is recommended to stick with a naming scheme that is independent of the "babelrc" name. @@ -221,7 +221,7 @@ to the [`"filename"`](#filename) provided to Babel. A `babelrc` value passed in the programmatic options will override one set within a configuration file. -Note: `.babelrc` files are only loaded if the current [`"filename"`](#filename) is inside of +Note: `.babelrc.*` files are only loaded if the current [`"filename"`](#filename) is inside of a package that matches one of the [`"babelrcRoots"`](#babelrcroots) packages. @@ -231,13 +231,13 @@ Type: `boolean | MatchPattern | Array`
Default: `opts.root`
Placement: Allowed in Babel's programmatic options, or inside of the loaded `configFile`. A programmatic option will override a config file one.
-By default, Babel will only search for `.babelrc` files within the [`"root"`](#root) package -because otherwise Babel cannot know if a given `.babelrc` is meant to be loaded, or +By default, Babel will only search for `.babelrc.*` files within the [`"root"`](#root) package +because otherwise Babel cannot know if a given `.babelrc.*` is meant to be loaded, or if it's [`"plugins"`](#plugins) and [`"presets"`](#presets) have even been installed, since the file being compiled could be inside `node_modules`, or have been symlinked into the project. This option allows users to provide a list of other packages that should be considered -"root" packages when considering whether to load `.babelrc` files. +"root" packages when considering whether to load `.babelrc.*` files. For example, a monorepo setup that wishes to allow individual packages to have their own configs might want to do @@ -247,7 +247,7 @@ babelrcRoots: [ // Keep the root as a root ".", - // Also consider monorepo packages "root" and load their .babelrc files. + // Also consider monorepo packages "root" and load their .babelrc.* files. "./packages/*" ] ``` diff --git a/docs/plugin-external-helpers.md b/docs/plugin-external-helpers.md index 134cf717bb..c92fdc7950 100644 --- a/docs/plugin-external-helpers.md +++ b/docs/plugin-external-helpers.md @@ -10,9 +10,7 @@ npm install --save-dev @babel/plugin-external-helpers ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-builtins.md b/docs/plugin-minify-builtins.md index a17fb232fd..e16e658d44 100644 --- a/docs/plugin-minify-builtins.md +++ b/docs/plugin-minify-builtins.md @@ -28,9 +28,8 @@ npm install babel-plugin-minify-builtins --save-dev ## Usage -### Via `.babelrc` (Recommended) +### With a configuration file (Recommended) -**.babelrc** ```json { diff --git a/docs/plugin-minify-constant-folding.md b/docs/plugin-minify-constant-folding.md index 5380f4699a..cd10ce5fbe 100644 --- a/docs/plugin-minify-constant-folding.md +++ b/docs/plugin-minify-constant-folding.md @@ -63,9 +63,7 @@ npm install babel-plugin-minify-constant-folding --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-dead-code-elimination.md b/docs/plugin-minify-dead-code-elimination.md index a694b62fef..9cee39efdf 100644 --- a/docs/plugin-minify-dead-code-elimination.md +++ b/docs/plugin-minify-dead-code-elimination.md @@ -38,9 +38,7 @@ npm install babel-plugin-minify-dead-code-elimination --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json // without options diff --git a/docs/plugin-minify-flip-comparisons.md b/docs/plugin-minify-flip-comparisons.md index a7c88f56c3..24cc8f8023 100644 --- a/docs/plugin-minify-flip-comparisons.md +++ b/docs/plugin-minify-flip-comparisons.md @@ -32,9 +32,7 @@ npm install babel-plugin-minify-flip-comparisons --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-guarded-expressions.md b/docs/plugin-minify-guarded-expressions.md index 9f35fcd1ae..bd5e87a6c6 100644 --- a/docs/plugin-minify-guarded-expressions.md +++ b/docs/plugin-minify-guarded-expressions.md @@ -26,9 +26,7 @@ npm install babel-plugin-minify-guarded-expressions --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-infinity.md b/docs/plugin-minify-infinity.md index 52adc23e19..fe74585d4e 100644 --- a/docs/plugin-minify-infinity.md +++ b/docs/plugin-minify-infinity.md @@ -24,9 +24,7 @@ npm install babel-plugin-minify-infinity --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-mangle-names.md b/docs/plugin-minify-mangle-names.md index 6e8cf99ed5..f01c8f29f5 100644 --- a/docs/plugin-minify-mangle-names.md +++ b/docs/plugin-minify-mangle-names.md @@ -38,9 +38,7 @@ npm install babel-plugin-minify-mangle-names --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json // without options diff --git a/docs/plugin-minify-numeric-literals.md b/docs/plugin-minify-numeric-literals.md index f9cd602b1c..8c2f95203b 100644 --- a/docs/plugin-minify-numeric-literals.md +++ b/docs/plugin-minify-numeric-literals.md @@ -26,9 +26,7 @@ npm install babel-plugin-minify-numeric-literals --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-replace.md b/docs/plugin-minify-replace.md index 4b520aa9f9..b905a6ac85 100644 --- a/docs/plugin-minify-replace.md +++ b/docs/plugin-minify-replace.md @@ -50,9 +50,7 @@ npm install babel-plugin-minify-replace --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json // without options diff --git a/docs/plugin-minify-simplify.md b/docs/plugin-minify-simplify.md index cde76bbc6e..13b2afee5e 100644 --- a/docs/plugin-minify-simplify.md +++ b/docs/plugin-minify-simplify.md @@ -58,9 +58,7 @@ npm install babel-plugin-minify-simplify --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-minify-type-constructors.md b/docs/plugin-minify-type-constructors.md index c73b708316..0b460bafdc 100644 --- a/docs/plugin-minify-type-constructors.md +++ b/docs/plugin-minify-type-constructors.md @@ -36,9 +36,7 @@ npm install babel-plugin-minify-type-constructors --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-async-generator-functions.md b/docs/plugin-proposal-async-generator-functions.md index 9d92a4c830..7dfbc7334e 100644 --- a/docs/plugin-proposal-async-generator-functions.md +++ b/docs/plugin-proposal-async-generator-functions.md @@ -80,9 +80,7 @@ npm install --save-dev @babel/plugin-proposal-async-generator-functions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-class-properties.md b/docs/plugin-proposal-class-properties.md index 9bd1868081..6356849257 100644 --- a/docs/plugin-proposal-class-properties.md +++ b/docs/plugin-proposal-class-properties.md @@ -44,9 +44,7 @@ npm install --save-dev @babel/plugin-proposal-class-properties ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-proposal-decorators.md b/docs/plugin-proposal-decorators.md index c6f9acd7dd..f0f1e44b20 100644 --- a/docs/plugin-proposal-decorators.md +++ b/docs/plugin-proposal-decorators.md @@ -56,7 +56,7 @@ npm install --save-dev @babel/plugin-proposal-decorators ## Usage -Add the following line to your .babelrc file: +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-do-expressions.md b/docs/plugin-proposal-do-expressions.md index 3f49b2b883..9ba3581991 100644 --- a/docs/plugin-proposal-do-expressions.md +++ b/docs/plugin-proposal-do-expressions.md @@ -90,9 +90,7 @@ npm install --save-dev @babel/plugin-proposal-do-expressions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-export-default-from.md b/docs/plugin-proposal-export-default-from.md index 4239cd512c..d402c7c45a 100644 --- a/docs/plugin-proposal-export-default-from.md +++ b/docs/plugin-proposal-export-default-from.md @@ -18,9 +18,7 @@ npm install --save-dev @babel/plugin-proposal-export-default-from ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-export-namespace-from.md b/docs/plugin-proposal-export-namespace-from.md index 8cf0353730..4d36fe4acd 100644 --- a/docs/plugin-proposal-export-namespace-from.md +++ b/docs/plugin-proposal-export-namespace-from.md @@ -18,9 +18,7 @@ npm install --save-dev @babel/plugin-proposal-export-namespace-from ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-function-bind.md b/docs/plugin-proposal-function-bind.md index 8dcc0f6daa..900719d7ab 100644 --- a/docs/plugin-proposal-function-bind.md +++ b/docs/plugin-proposal-function-bind.md @@ -93,9 +93,7 @@ npm install --save-dev @babel/plugin-proposal-function-bind ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-function-sent.md b/docs/plugin-proposal-function-sent.md index 67032e7299..8f9f451947 100644 --- a/docs/plugin-proposal-function-sent.md +++ b/docs/plugin-proposal-function-sent.md @@ -39,9 +39,7 @@ npm install --save-dev @babel/plugin-proposal-function-sent ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-json-strings.md b/docs/plugin-proposal-json-strings.md index 1774b62d79..a6f1459636 100644 --- a/docs/plugin-proposal-json-strings.md +++ b/docs/plugin-proposal-json-strings.md @@ -28,9 +28,7 @@ npm install --save-dev @babel/plugin-proposal-json-strings ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-logical-assignment-operators.md b/docs/plugin-proposal-logical-assignment-operators.md index c9632520fd..49920f4ce4 100644 --- a/docs/plugin-proposal-logical-assignment-operators.md +++ b/docs/plugin-proposal-logical-assignment-operators.md @@ -36,9 +36,7 @@ npm install --save-dev @babel/plugin-proposal-logical-assignment-operators ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-nullish-coalescing-operator.md b/docs/plugin-proposal-nullish-coalescing-operator.md index 71626010ff..fddf7a7d9b 100644 --- a/docs/plugin-proposal-nullish-coalescing-operator.md +++ b/docs/plugin-proposal-nullish-coalescing-operator.md @@ -31,9 +31,7 @@ npm install --save-dev @babel/plugin-proposal-nullish-coalescing-operator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-numeric-separator.md b/docs/plugin-proposal-numeric-separator.md index b60d6a46b3..1032e053a7 100644 --- a/docs/plugin-proposal-numeric-separator.md +++ b/docs/plugin-proposal-numeric-separator.md @@ -67,9 +67,7 @@ npm install --save-dev @babel/plugin-proposal-numeric-separator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { @@ -97,9 +95,7 @@ If you need to further compile ES2015 Decimal, Binary, Hex and Octal number repr > `@babel/plugin-transform-literals` is already included in [@babel/preset-env](preset-env.md) and @babel/preset-es2015. -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-object-rest-spread.md b/docs/plugin-proposal-object-rest-spread.md index bb6cbdbdc3..5f08258100 100644 --- a/docs/plugin-proposal-object-rest-spread.md +++ b/docs/plugin-proposal-object-rest-spread.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/plugin-proposal-object-rest-spread ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-optional-catch-binding.md b/docs/plugin-proposal-optional-catch-binding.md index 8a02c98d50..5d5fb7513f 100644 --- a/docs/plugin-proposal-optional-catch-binding.md +++ b/docs/plugin-proposal-optional-catch-binding.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-proposal-optional-catch-binding ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-optional-chaining.md b/docs/plugin-proposal-optional-chaining.md index 027b485bd5..c14b588340 100644 --- a/docs/plugin-proposal-optional-chaining.md +++ b/docs/plugin-proposal-optional-chaining.md @@ -94,9 +94,7 @@ npm install --save-dev @babel/plugin-proposal-optional-chaining ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-partial-application.md b/docs/plugin-proposal-partial-application.md index ed788e1bef..1d3e7af976 100644 --- a/docs/plugin-proposal-partial-application.md +++ b/docs/plugin-proposal-partial-application.md @@ -50,9 +50,7 @@ super(?) // `?` not supported in |SuperCall| $ npm install --save-dev @babel/plugin-proposal-partial-application ``` -## Usage - -Add the following line to your .babelrc file: +### With a configuration file (Recommended) ```json { @@ -60,6 +58,8 @@ Add the following line to your .babelrc file: } ``` +### Via CLI + ```sh babel --plugins @babel/plugin-proposal-partial-application script.js ``` diff --git a/docs/plugin-proposal-pipeline-operator.md b/docs/plugin-proposal-pipeline-operator.md index f030ee1dc1..b97ee99988 100644 --- a/docs/plugin-proposal-pipeline-operator.md +++ b/docs/plugin-proposal-pipeline-operator.md @@ -12,9 +12,7 @@ $ npm install --save-dev @babel/plugin-proposal-pipeline-operator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-private-methods.md b/docs/plugin-proposal-private-methods.md index a64cf3084c..c88860dc94 100644 --- a/docs/plugin-proposal-private-methods.md +++ b/docs/plugin-proposal-private-methods.md @@ -31,9 +31,7 @@ $ npm install @babel/plugin-proposal-private-methods ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-proposal-throw-expressions.md b/docs/plugin-proposal-throw-expressions.md index a7ba09aa89..d4c7bd90b5 100644 --- a/docs/plugin-proposal-throw-expressions.md +++ b/docs/plugin-proposal-throw-expressions.md @@ -20,9 +20,7 @@ npm install --save-dev @babel/plugin-proposal-throw-expressions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-proposal-unicode-property-regex.md b/docs/plugin-proposal-unicode-property-regex.md index d57a880a8f..1249599952 100644 --- a/docs/plugin-proposal-unicode-property-regex.md +++ b/docs/plugin-proposal-unicode-property-regex.md @@ -14,9 +14,7 @@ npm install --save-dev @babel/plugin-proposal-unicode-property-regex ## Usage -### Via `.babelrc` (recommended) - -`.babelrc` +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-async-generators.md b/docs/plugin-syntax-async-generators.md index 505661373b..ee4ab7473a 100644 --- a/docs/plugin-syntax-async-generators.md +++ b/docs/plugin-syntax-async-generators.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-syntax-async-generators ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-bigint.md b/docs/plugin-syntax-bigint.md index dd871d4265..34caea1ffd 100644 --- a/docs/plugin-syntax-bigint.md +++ b/docs/plugin-syntax-bigint.md @@ -13,9 +13,7 @@ npm install --save-dev @babel/plugin-syntax-bigint ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-class-properties.md b/docs/plugin-syntax-class-properties.md index d7f7f5d3f0..d31f1ab310 100644 --- a/docs/plugin-syntax-class-properties.md +++ b/docs/plugin-syntax-class-properties.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-class-properties ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-decorators.md b/docs/plugin-syntax-decorators.md index 62c1b90036..3fd22a6256 100644 --- a/docs/plugin-syntax-decorators.md +++ b/docs/plugin-syntax-decorators.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-decorators ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-do-expressions.md b/docs/plugin-syntax-do-expressions.md index 1efba4ae18..343bf1bf2d 100644 --- a/docs/plugin-syntax-do-expressions.md +++ b/docs/plugin-syntax-do-expressions.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-do-expressions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-dynamic-import.md b/docs/plugin-syntax-dynamic-import.md index d06439126d..1dd1834313 100644 --- a/docs/plugin-syntax-dynamic-import.md +++ b/docs/plugin-syntax-dynamic-import.md @@ -12,9 +12,7 @@ npm install --save-dev @babel/plugin-syntax-dynamic-import ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-export-default-from.md b/docs/plugin-syntax-export-default-from.md index 63410e52f0..34142b80af 100644 --- a/docs/plugin-syntax-export-default-from.md +++ b/docs/plugin-syntax-export-default-from.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-export-default-from ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-export-namespace-from.md b/docs/plugin-syntax-export-namespace-from.md index c384dd2653..895bcf92b5 100644 --- a/docs/plugin-syntax-export-namespace-from.md +++ b/docs/plugin-syntax-export-namespace-from.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-export-namespace-from ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-flow.md b/docs/plugin-syntax-flow.md index 22f80f5297..62061f56c7 100644 --- a/docs/plugin-syntax-flow.md +++ b/docs/plugin-syntax-flow.md @@ -12,9 +12,7 @@ npm install --save-dev @babel/plugin-syntax-flow ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-function-bind.md b/docs/plugin-syntax-function-bind.md index c1eb35cd91..dd0b612d0f 100644 --- a/docs/plugin-syntax-function-bind.md +++ b/docs/plugin-syntax-function-bind.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-function-bind ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-function-sent.md b/docs/plugin-syntax-function-sent.md index fc8f0461d6..bd53352ebf 100644 --- a/docs/plugin-syntax-function-sent.md +++ b/docs/plugin-syntax-function-sent.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-function-sent ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-import-meta.md b/docs/plugin-syntax-import-meta.md index 2f3f77f5be..7562dd363a 100644 --- a/docs/plugin-syntax-import-meta.md +++ b/docs/plugin-syntax-import-meta.md @@ -12,9 +12,7 @@ npm install --save-dev @babel/plugin-syntax-import-meta ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-json-strings.md b/docs/plugin-syntax-json-strings.md index 0376dab4c4..f98fe2cf48 100644 --- a/docs/plugin-syntax-json-strings.md +++ b/docs/plugin-syntax-json-strings.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-json-strings ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-jsx.md b/docs/plugin-syntax-jsx.md index 2648012363..3c1e66e320 100644 --- a/docs/plugin-syntax-jsx.md +++ b/docs/plugin-syntax-jsx.md @@ -12,9 +12,7 @@ npm install --save-dev @babel/plugin-syntax-jsx ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-logical-assignment-operators.md b/docs/plugin-syntax-logical-assignment-operators.md index 8a45462fa8..e1e89f4a4e 100644 --- a/docs/plugin-syntax-logical-assignment-operators.md +++ b/docs/plugin-syntax-logical-assignment-operators.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-logical-assignment-operators ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-nullish-coalescing-operator.md b/docs/plugin-syntax-nullish-coalescing-operator.md index 089134c2a4..0c1f42f230 100644 --- a/docs/plugin-syntax-nullish-coalescing-operator.md +++ b/docs/plugin-syntax-nullish-coalescing-operator.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-nullish-coalescing-operator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-numeric-separator.md b/docs/plugin-syntax-numeric-separator.md index 7114743512..d2198609a2 100644 --- a/docs/plugin-syntax-numeric-separator.md +++ b/docs/plugin-syntax-numeric-separator.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-numeric-separator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-object-rest-spread.md b/docs/plugin-syntax-object-rest-spread.md index a1f8510312..4567a981a8 100644 --- a/docs/plugin-syntax-object-rest-spread.md +++ b/docs/plugin-syntax-object-rest-spread.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-object-rest-spread ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-optional-catch-binding.md b/docs/plugin-syntax-optional-catch-binding.md index f8437def3f..6aab814149 100644 --- a/docs/plugin-syntax-optional-catch-binding.md +++ b/docs/plugin-syntax-optional-catch-binding.md @@ -29,9 +29,7 @@ npm install --save-dev @babel/plugin-syntax-optional-catch-binding ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-optional-chaining.md b/docs/plugin-syntax-optional-chaining.md index d5078ee69a..2ecc3dec2e 100644 --- a/docs/plugin-syntax-optional-chaining.md +++ b/docs/plugin-syntax-optional-chaining.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-optional-chaining ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-partial-application.md b/docs/plugin-syntax-partial-application.md index 3251d1db2b..6b8b14360d 100644 --- a/docs/plugin-syntax-partial-application.md +++ b/docs/plugin-syntax-partial-application.md @@ -16,9 +16,7 @@ npm install --save-dev @babel/plugin-syntax-partial-application ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-pipeline-operator.md b/docs/plugin-syntax-pipeline-operator.md index adf0983917..191165eb7e 100644 --- a/docs/plugin-syntax-pipeline-operator.md +++ b/docs/plugin-syntax-pipeline-operator.md @@ -16,9 +16,7 @@ $ npm install @babel/plugin-syntax-pipeline-operator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-throw-expressions.md b/docs/plugin-syntax-throw-expressions.md index 04891d255a..81a3e8f6bf 100644 --- a/docs/plugin-syntax-throw-expressions.md +++ b/docs/plugin-syntax-throw-expressions.md @@ -23,9 +23,7 @@ npm install --save-dev @babel/plugin-syntax-throw-expressions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-top-level-await.md b/docs/plugin-syntax-top-level-await.md index d7ba1e4d9d..06ceecb621 100644 --- a/docs/plugin-syntax-top-level-await.md +++ b/docs/plugin-syntax-top-level-await.md @@ -24,9 +24,7 @@ npm install --save-dev @babel/plugin-syntax-top-level-await ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-syntax-typescript.md b/docs/plugin-syntax-typescript.md index 2431142e4e..4ccb743a64 100644 --- a/docs/plugin-syntax-typescript.md +++ b/docs/plugin-syntax-typescript.md @@ -10,9 +10,7 @@ npm install --save-dev @babel/plugin-syntax-typescript ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-arrow-functions.md b/docs/plugin-transform-arrow-functions.md index 0311e647a0..1c515f3e14 100644 --- a/docs/plugin-transform-arrow-functions.md +++ b/docs/plugin-transform-arrow-functions.md @@ -61,9 +61,7 @@ npm install --save-dev @babel/plugin-transform-arrow-functions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-async-to-generator.md b/docs/plugin-transform-async-to-generator.md index a24c44748d..f4e500eecc 100644 --- a/docs/plugin-transform-async-to-generator.md +++ b/docs/plugin-transform-async-to-generator.md @@ -47,9 +47,7 @@ npm install --save-dev @babel/plugin-transform-async-to-generator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-block-scoped-functions.md b/docs/plugin-transform-block-scoped-functions.md index 1157d45197..91ce4f2a08 100644 --- a/docs/plugin-transform-block-scoped-functions.md +++ b/docs/plugin-transform-block-scoped-functions.md @@ -37,9 +37,7 @@ npm install --save-dev @babel/plugin-transform-block-scoped-functions ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-block-scoping.md b/docs/plugin-transform-block-scoping.md index 49a1e1f190..9aac568498 100644 --- a/docs/plugin-transform-block-scoping.md +++ b/docs/plugin-transform-block-scoping.md @@ -39,9 +39,7 @@ npm install --save-dev @babel/plugin-transform-block-scoping ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-classes.md b/docs/plugin-transform-classes.md index a3e1abe2a0..79e5c60607 100644 --- a/docs/plugin-transform-classes.md +++ b/docs/plugin-transform-classes.md @@ -78,9 +78,7 @@ npm install --save-dev @babel/plugin-transform-classes ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```js // without options diff --git a/docs/plugin-transform-computed-properties.md b/docs/plugin-transform-computed-properties.md index aafcca74e7..57a25b7b5e 100644 --- a/docs/plugin-transform-computed-properties.md +++ b/docs/plugin-transform-computed-properties.md @@ -55,9 +55,7 @@ npm install --save-dev @babel/plugin-transform-computed-properties ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-destructuring.md b/docs/plugin-transform-destructuring.md index 309e03245d..6e998b980c 100644 --- a/docs/plugin-transform-destructuring.md +++ b/docs/plugin-transform-destructuring.md @@ -38,9 +38,7 @@ npm install --save-dev @babel/plugin-transform-destructuring ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-duplicate-keys.md b/docs/plugin-transform-duplicate-keys.md index 7ae76b365c..78aa1303b2 100644 --- a/docs/plugin-transform-duplicate-keys.md +++ b/docs/plugin-transform-duplicate-keys.md @@ -38,9 +38,7 @@ npm install --save-dev @babel/plugin-transform-duplicate-keys ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-exponentiation-operator.md b/docs/plugin-transform-exponentiation-operator.md index 1269061e56..68701e4de6 100644 --- a/docs/plugin-transform-exponentiation-operator.md +++ b/docs/plugin-transform-exponentiation-operator.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/plugin-transform-exponentiation-operator ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-flow-comments.md b/docs/plugin-transform-flow-comments.md index 9384748368..9265d177d3 100644 --- a/docs/plugin-transform-flow-comments.md +++ b/docs/plugin-transform-flow-comments.md @@ -48,9 +48,7 @@ npm install --save-dev @babel/plugin-transform-flow-comments ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-flow-strip-types.md b/docs/plugin-transform-flow-strip-types.md index 45e633ad11..e9f36da7c5 100644 --- a/docs/plugin-transform-flow-strip-types.md +++ b/docs/plugin-transform-flow-strip-types.md @@ -26,9 +26,7 @@ npm install --save-dev @babel/plugin-transform-flow-strip-types ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-for-of.md b/docs/plugin-transform-for-of.md index 4a1338951c..5289acd3af 100644 --- a/docs/plugin-transform-for-of.md +++ b/docs/plugin-transform-for-of.md @@ -47,9 +47,7 @@ npm install --save-dev @babel/plugin-transform-for-of ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-function-name.md b/docs/plugin-transform-function-name.md index dc79931b67..bf97ab9783 100644 --- a/docs/plugin-transform-function-name.md +++ b/docs/plugin-transform-function-name.md @@ -28,9 +28,7 @@ npm install --save-dev @babel/plugin-transform-function-name ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-inline-consecutive-adds.md b/docs/plugin-transform-inline-consecutive-adds.md index 58f6a4c24e..03781594bc 100644 --- a/docs/plugin-transform-inline-consecutive-adds.md +++ b/docs/plugin-transform-inline-consecutive-adds.md @@ -43,9 +43,7 @@ npm install babel-plugin-transform-inline-consecutive-adds --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-inline-environment-variables.md b/docs/plugin-transform-inline-environment-variables.md index 510514197c..e97f448ccc 100644 --- a/docs/plugin-transform-inline-environment-variables.md +++ b/docs/plugin-transform-inline-environment-variables.md @@ -27,9 +27,7 @@ npm install babel-plugin-transform-inline-environment-variables --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json // without options diff --git a/docs/plugin-transform-instanceof.md b/docs/plugin-transform-instanceof.md index 51de643226..361dbb6537 100644 --- a/docs/plugin-transform-instanceof.md +++ b/docs/plugin-transform-instanceof.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-transform-instanceof ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-jscript.md b/docs/plugin-transform-jscript.md index 2c1b6cde23..ce7de14b6a 100644 --- a/docs/plugin-transform-jscript.md +++ b/docs/plugin-transform-jscript.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-transform-jscript ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-literals.md b/docs/plugin-transform-literals.md index b0ffc250ba..e7d8a9827b 100644 --- a/docs/plugin-transform-literals.md +++ b/docs/plugin-transform-literals.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/plugin-transform-literals ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-member-expression-literals.md b/docs/plugin-transform-member-expression-literals.md index 025716b098..433cffd10d 100644 --- a/docs/plugin-transform-member-expression-literals.md +++ b/docs/plugin-transform-member-expression-literals.md @@ -32,9 +32,7 @@ npm install @babel/plugin-transform-member-expression-literals --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-merge-sibling-variables.md b/docs/plugin-transform-merge-sibling-variables.md index ac9476ab9f..5227f4184a 100644 --- a/docs/plugin-transform-merge-sibling-variables.md +++ b/docs/plugin-transform-merge-sibling-variables.md @@ -37,9 +37,7 @@ npm install babel-plugin-transform-merge-sibling-variables --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-minify-booleans.md b/docs/plugin-transform-minify-booleans.md index e1836e60c6..ef010b3c5f 100644 --- a/docs/plugin-transform-minify-booleans.md +++ b/docs/plugin-transform-minify-booleans.md @@ -28,9 +28,7 @@ npm install babel-plugin-transform-minify-booleans --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-modules-amd.md b/docs/plugin-transform-modules-amd.md index 78c66e1fa9..86af05a950 100644 --- a/docs/plugin-transform-modules-amd.md +++ b/docs/plugin-transform-modules-amd.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-transform-modules-amd ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-modules-commonjs.md b/docs/plugin-transform-modules-commonjs.md index fd25e876a3..5800158782 100644 --- a/docs/plugin-transform-modules-commonjs.md +++ b/docs/plugin-transform-modules-commonjs.md @@ -32,9 +32,7 @@ npm install --save-dev @babel/plugin-transform-modules-commonjs ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```js // without options diff --git a/docs/plugin-transform-modules-systemjs.md b/docs/plugin-transform-modules-systemjs.md index c75cfe08d0..48518ad1e7 100644 --- a/docs/plugin-transform-modules-systemjs.md +++ b/docs/plugin-transform-modules-systemjs.md @@ -35,9 +35,7 @@ npm install --save-dev @babel/plugin-transform-modules-systemjs ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-modules-umd.md b/docs/plugin-transform-modules-umd.md index 0e632dc60f..776951c2d0 100644 --- a/docs/plugin-transform-modules-umd.md +++ b/docs/plugin-transform-modules-umd.md @@ -46,9 +46,7 @@ npm install --save-dev @babel/plugin-transform-modules-umd ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-named-capturing-groups-regex.md b/docs/plugin-transform-named-capturing-groups-regex.md index 3200854587..37df344690 100644 --- a/docs/plugin-transform-named-capturing-groups-regex.md +++ b/docs/plugin-transform-named-capturing-groups-regex.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-transform-named-capturing-groups-regex ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-new-target.md b/docs/plugin-transform-new-target.md index 6d66acdd74..613acddd89 100644 --- a/docs/plugin-transform-new-target.md +++ b/docs/plugin-transform-new-target.md @@ -81,9 +81,7 @@ npm install --save-dev @babel/plugin-transform-new-target ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-node-env-inline.md b/docs/plugin-transform-node-env-inline.md index 0fe6588d87..8faf9cb4b1 100644 --- a/docs/plugin-transform-node-env-inline.md +++ b/docs/plugin-transform-node-env-inline.md @@ -33,9 +33,7 @@ npm install babel-plugin-transform-node-env-inline --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-object-assign.md b/docs/plugin-transform-object-assign.md index a13b646ea9..d8192f9dcc 100644 --- a/docs/plugin-transform-object-assign.md +++ b/docs/plugin-transform-object-assign.md @@ -37,9 +37,7 @@ npm install --save-dev @babel/plugin-transform-object-assign ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-object-set-prototype-of-to-assign.md b/docs/plugin-transform-object-set-prototype-of-to-assign.md index bf435cff9c..235f4ad8a5 100644 --- a/docs/plugin-transform-object-set-prototype-of-to-assign.md +++ b/docs/plugin-transform-object-set-prototype-of-to-assign.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/plugin-transform-object-set-prototype-of-to-assign ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-object-super.md b/docs/plugin-transform-object-super.md index 9b43066eba..42b917453c 100644 --- a/docs/plugin-transform-object-super.md +++ b/docs/plugin-transform-object-super.md @@ -50,9 +50,7 @@ npm install --save-dev @babel/plugin-transform-object-super ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-parameters.md b/docs/plugin-transform-parameters.md index c195917d15..b9d773fc53 100644 --- a/docs/plugin-transform-parameters.md +++ b/docs/plugin-transform-parameters.md @@ -58,9 +58,7 @@ not supported in your environment then you'll need the ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-property-literals.md b/docs/plugin-transform-property-literals.md index c191783fc0..75377e0000 100644 --- a/docs/plugin-transform-property-literals.md +++ b/docs/plugin-transform-property-literals.md @@ -42,9 +42,7 @@ npm install @babel/plugin-transform-property-literals --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-property-mutators.md b/docs/plugin-transform-property-mutators.md index 609a0adb20..f1e326da8f 100644 --- a/docs/plugin-transform-property-mutators.md +++ b/docs/plugin-transform-property-mutators.md @@ -44,9 +44,7 @@ npm install --save-dev @babel/plugin-transform-property-mutators ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-proto-to-assign.md b/docs/plugin-transform-proto-to-assign.md index 93bb118d71..f28d2417c1 100644 --- a/docs/plugin-transform-proto-to-assign.md +++ b/docs/plugin-transform-proto-to-assign.md @@ -53,9 +53,7 @@ npm install --save-dev @babel/plugin-transform-proto-to-assign ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-constant-elements.md b/docs/plugin-transform-react-constant-elements.md index 3ed1e12b8a..5f0e4b9bbc 100644 --- a/docs/plugin-transform-react-constant-elements.md +++ b/docs/plugin-transform-react-constant-elements.md @@ -58,9 +58,7 @@ npm install --save-dev @babel/plugin-transform-react-constant-elements ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-display-name.md b/docs/plugin-transform-react-display-name.md index 8095b2d310..db2050a8fd 100644 --- a/docs/plugin-transform-react-display-name.md +++ b/docs/plugin-transform-react-display-name.md @@ -32,9 +32,7 @@ npm install --save-dev @babel/plugin-transform-react-display-name ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-inline-elements.md b/docs/plugin-transform-react-inline-elements.md index 991bdc125f..f849ae6fdd 100644 --- a/docs/plugin-transform-react-inline-elements.md +++ b/docs/plugin-transform-react-inline-elements.md @@ -55,9 +55,7 @@ npm install --save-dev @babel/plugin-transform-react-inline-elements ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-jsx-compat.md b/docs/plugin-transform-react-jsx-compat.md index aa972ff724..c09ecf8af8 100644 --- a/docs/plugin-transform-react-jsx-compat.md +++ b/docs/plugin-transform-react-jsx-compat.md @@ -32,9 +32,7 @@ npm install --save-dev @babel/plugin-transform-react-jsx-compat ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-jsx-self.md b/docs/plugin-transform-react-jsx-self.md index e5e9ba204f..a83495d29c 100644 --- a/docs/plugin-transform-react-jsx-self.md +++ b/docs/plugin-transform-react-jsx-self.md @@ -26,9 +26,7 @@ npm install --save-dev @babel/plugin-transform-react-jsx-self ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-jsx-source.md b/docs/plugin-transform-react-jsx-source.md index 0772b044b2..6242d3fdde 100644 --- a/docs/plugin-transform-react-jsx-source.md +++ b/docs/plugin-transform-react-jsx-source.md @@ -26,9 +26,7 @@ npm install --save-dev @babel/plugin-transform-react-jsx-source ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-react-jsx.md b/docs/plugin-transform-react-jsx.md index 34927c0856..801cd75e33 100644 --- a/docs/plugin-transform-react-jsx.md +++ b/docs/plugin-transform-react-jsx.md @@ -130,9 +130,7 @@ npm install --save-dev @babel/plugin-transform-react-jsx ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-regenerator.md b/docs/plugin-transform-regenerator.md index 3bccbced56..180695bb6d 100644 --- a/docs/plugin-transform-regenerator.md +++ b/docs/plugin-transform-regenerator.md @@ -44,7 +44,7 @@ npm install --save-dev @babel/plugin-transform-regenerator ## Usage -### Via `.babelrc` (Recommended) +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-regexp-constructors.md b/docs/plugin-transform-regexp-constructors.md index f8a8f1e453..8b9cb4dae9 100644 --- a/docs/plugin-transform-regexp-constructors.md +++ b/docs/plugin-transform-regexp-constructors.md @@ -28,9 +28,7 @@ npm install babel-plugin-transform-regexp-constructors --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-remove-console.md b/docs/plugin-transform-remove-console.md index cac04d16f3..04b9a78d7a 100644 --- a/docs/plugin-transform-remove-console.md +++ b/docs/plugin-transform-remove-console.md @@ -26,9 +26,7 @@ npm install babel-plugin-transform-remove-console --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json // without options diff --git a/docs/plugin-transform-remove-debugger.md b/docs/plugin-transform-remove-debugger.md index 8940f1d1e2..55d973ed88 100644 --- a/docs/plugin-transform-remove-debugger.md +++ b/docs/plugin-transform-remove-debugger.md @@ -25,9 +25,7 @@ npm install babel-plugin-transform-remove-debugger --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-remove-undefined.md b/docs/plugin-transform-remove-undefined.md index 0cf9fbc887..1ad8b2d6c2 100644 --- a/docs/plugin-transform-remove-undefined.md +++ b/docs/plugin-transform-remove-undefined.md @@ -36,9 +36,7 @@ npm install babel-plugin-transform-remove-undefined --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-reserved-words.md b/docs/plugin-transform-reserved-words.md index 24cca4c6b9..78a2a5b1d1 100644 --- a/docs/plugin-transform-reserved-words.md +++ b/docs/plugin-transform-reserved-words.md @@ -32,9 +32,7 @@ npm install --save-dev @babel/plugin-transform-reserved-words ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-runtime.md b/docs/plugin-transform-runtime.md index e01d98dcaa..3a5dc79125 100644 --- a/docs/plugin-transform-runtime.md +++ b/docs/plugin-transform-runtime.md @@ -38,9 +38,7 @@ See the [technical details](#technical-details) section for more information on ## Usage -### Via `.babelrc` (Recommended) - -Add the following line to your `.babelrc` file: +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-shorthand-properties.md b/docs/plugin-transform-shorthand-properties.md index 2ddf89198b..7431d7d0f2 100644 --- a/docs/plugin-transform-shorthand-properties.md +++ b/docs/plugin-transform-shorthand-properties.md @@ -46,9 +46,7 @@ npm install --save-dev @babel/plugin-transform-shorthand-properties ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-simplify-comparison-operators.md b/docs/plugin-transform-simplify-comparison-operators.md index 3204cb4373..16583220fd 100644 --- a/docs/plugin-transform-simplify-comparison-operators.md +++ b/docs/plugin-transform-simplify-comparison-operators.md @@ -26,9 +26,7 @@ npm install babel-plugin-transform-simplify-comparison-operators --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-spread.md b/docs/plugin-transform-spread.md index 0c6c426a56..c52d22ad64 100644 --- a/docs/plugin-transform-spread.md +++ b/docs/plugin-transform-spread.md @@ -34,9 +34,7 @@ npm install --save-dev @babel/plugin-transform-spread ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-sticky-regex.md b/docs/plugin-transform-sticky-regex.md index 8f097c6b20..be57d095a2 100644 --- a/docs/plugin-transform-sticky-regex.md +++ b/docs/plugin-transform-sticky-regex.md @@ -26,9 +26,7 @@ npm install --save-dev @babel/plugin-transform-sticky-regex ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-strict-mode.md b/docs/plugin-transform-strict-mode.md index 62dbbbbdd7..925e078030 100644 --- a/docs/plugin-transform-strict-mode.md +++ b/docs/plugin-transform-strict-mode.md @@ -32,9 +32,7 @@ npm install --save-dev @babel/plugin-transform-strict-mode ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json diff --git a/docs/plugin-transform-template-literals.md b/docs/plugin-transform-template-literals.md index 8daf5d2727..4b47cc4ee0 100644 --- a/docs/plugin-transform-template-literals.md +++ b/docs/plugin-transform-template-literals.md @@ -26,9 +26,7 @@ npm install --save-dev @babel/plugin-transform-template-literals ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/plugin-transform-typeof-symbol.md b/docs/plugin-transform-typeof-symbol.md index b2042fdd05..110c151e73 100644 --- a/docs/plugin-transform-typeof-symbol.md +++ b/docs/plugin-transform-typeof-symbol.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/plugin-transform-typeof-symbol ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-typescript.md b/docs/plugin-transform-typescript.md index 8035a7fbf7..cf081a2bfc 100644 --- a/docs/plugin-transform-typescript.md +++ b/docs/plugin-transform-typescript.md @@ -28,9 +28,7 @@ npm install --save-dev @babel/plugin-transform-typescript ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { @@ -201,7 +199,7 @@ equivalents in Babel can be enabled by some configuration options or plugins. - `--importHelpers` This is the equivalent of the `@babel/plugin-transform-runtime` package. - `--inlineSourceMap` - You can set the [`sourceMaps: "inline"`](https://babeljs.io/docs/en/options#sourcemaps) option in your `babel.config.js` file. + You can set the [`sourceMaps: "inline"`](https://babeljs.io/docs/en/options#sourcemaps) option in your `babel.config.*` file. - `--isolatedModules` This is the default Babel behavior, and it can't be turned off because Babel doesn't support cross-file analysis. - `--jsx` diff --git a/docs/plugin-transform-undefined-to-void.md b/docs/plugin-transform-undefined-to-void.md index 6ef255e62e..a7f8ca3e6f 100644 --- a/docs/plugin-transform-undefined-to-void.md +++ b/docs/plugin-transform-undefined-to-void.md @@ -28,9 +28,7 @@ npm install babel-plugin-transform-undefined-to-void --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/plugin-transform-unicode-regex.md b/docs/plugin-transform-unicode-regex.md index 9c01fae414..431ece49d0 100644 --- a/docs/plugin-transform-unicode-regex.md +++ b/docs/plugin-transform-unicode-regex.md @@ -28,9 +28,7 @@ npm install --save-dev @babel/plugin-transform-unicode-regex ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-es2015.md b/docs/preset-es2015.md index dccc2eb5ab..f6c83fb22a 100644 --- a/docs/preset-es2015.md +++ b/docs/preset-es2015.md @@ -15,9 +15,7 @@ npm install --save-dev @babel/preset-es2015 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-es2016.md b/docs/preset-es2016.md index 85d46583de..024907ba67 100644 --- a/docs/preset-es2016.md +++ b/docs/preset-es2016.md @@ -15,9 +15,7 @@ npm install --save-dev @babel/preset-es2016 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-es2017.md b/docs/preset-es2017.md index b76b6552cb..23fcb9f721 100644 --- a/docs/preset-es2017.md +++ b/docs/preset-es2017.md @@ -15,9 +15,7 @@ npm install --save-dev @babel/preset-es2017 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-flow.md b/docs/preset-flow.md index 232845ca28..93ec690054 100644 --- a/docs/preset-flow.md +++ b/docs/preset-flow.md @@ -30,9 +30,7 @@ npm install --save-dev @babel/preset-flow ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-minify.md b/docs/preset-minify.md index 3c307f09f4..73376a5a40 100644 --- a/docs/preset-minify.md +++ b/docs/preset-minify.md @@ -16,9 +16,7 @@ npm install babel-preset-minify --save-dev ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-react.md b/docs/preset-react.md index 4e640234f7..61dd131c22 100644 --- a/docs/preset-react.md +++ b/docs/preset-react.md @@ -27,9 +27,7 @@ npm install --save-dev @babel/preset-react ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) Without options: diff --git a/docs/preset-stage-0.md b/docs/preset-stage-0.md index 3efa400339..b8cba769a8 100644 --- a/docs/preset-stage-0.md +++ b/docs/preset-stage-0.md @@ -17,9 +17,7 @@ npm install --save-dev @babel/preset-stage-0 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-stage-1.md b/docs/preset-stage-1.md index cffc8e9c6a..6907a86e0f 100644 --- a/docs/preset-stage-1.md +++ b/docs/preset-stage-1.md @@ -27,9 +27,7 @@ npm install --save-dev @babel/preset-stage-1 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-stage-2.md b/docs/preset-stage-2.md index 00b4044fc9..e8a6f2ceeb 100644 --- a/docs/preset-stage-2.md +++ b/docs/preset-stage-2.md @@ -27,9 +27,7 @@ npm install --save-dev @babel/preset-stage-2 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-stage-3.md b/docs/preset-stage-3.md index 6e847077ea..7fe56a8228 100644 --- a/docs/preset-stage-3.md +++ b/docs/preset-stage-3.md @@ -27,9 +27,7 @@ npm install --save-dev @babel/preset-stage-3 ## Usage -### Via `.babelrc` (Recommended) - -**.babelrc** +### With a configuration file (Recommended) ```json { diff --git a/docs/preset-typescript.md b/docs/preset-typescript.md index 89becea7e7..00e2c59583 100644 --- a/docs/preset-typescript.md +++ b/docs/preset-typescript.md @@ -32,9 +32,8 @@ npm install --save-dev @babel/preset-typescript ## Usage -### Via `.babelrc` (Recommended) +### With a configuration file (Recommended) -**.babelrc** ```json { diff --git a/docs/usage.md b/docs/usage.md index 8d121c2cd0..3a01962ff0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -20,25 +20,25 @@ The entire process to set this up involves: npm install --save @babel/polyfill ``` -2. Creating a config file named `babel.config.js` in the root of your project with this content: - - ```js - const presets = [ - [ - "@babel/env", - { - targets: { - edge: "17", - firefox: "60", - chrome: "67", - safari: "11.1", - }, - useBuiltIns: "usage", - }, - ], - ]; - - module.exports = { presets }; +2. Creating a config file named `babel.config.json` in the root of your project with this content: + + ```json + { + "presets": [ + [ + "@babel/env", + { + "targets": { + "edge": "17", + "firefox": "60", + "chrome": "67", + "safari": "11.1", + }, + "useBuiltIns": "usage", + } + ] + ] + } ``` > The browsers list above is just an arbitrary example. You will have to adapt it for the browsers you want to support. @@ -127,7 +127,7 @@ Without any configuration, this preset will include all plugins to support moder > There are a few different ways to use configuration files depending on your needs. Be sure to read our in-depth guide on how to [configure Babel](configuration.md) for more information. -For now, let's create a file called `babel.config.js` with the following content: +For now, let's create a file called `babel.config.json` with the following content: ```js const presets = [ @@ -175,23 +175,23 @@ npm install --save @babel/polyfill Now luckily for us, we're using the `env` preset which has a `"useBuiltIns"` option that when set to `"usage"` will practically apply the last optimization mentioned above where you only include the polyfills you need. With this new option the configuration changes like this: -```js -const presets = [ - [ - "@babel/env", - { - targets: { - edge: "17", - firefox: "60", - chrome: "67", - safari: "11.1", - }, - useBuiltIns: "usage", - }, - ], -]; - -module.exports = { presets }; +```json +{ + "presets": [ + [ + "@babel/env", + { + "targets": { + "edge": "17", + "firefox": "60", + "chrome": "67", + "safari": "11.1", + }, + "useBuiltIns": "usage", + } + ] + ] +} ``` Babel will now inspect all your code for features that are missing in your target environments and include only the required polyfills. For example this code: From 770d95a6446760305351d1dd0ea9ae4e2c293182 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Ribaudo?= Date: Fri, 10 Jan 2020 21:10:45 +0100 Subject: [PATCH 2/5] Update docs/configuration.md Co-Authored-By: Jayden Seric --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5d1694cd8a..f8c0a11de0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -77,7 +77,7 @@ Alternatively, you can choose to specify your [`.babelrc.json`](#babelrc) config } ``` -### JavaScript configuratino files +### JavaScript configuration files You can also write `babel.config.json` and `.babelrc.json` files using JavaScript: From 85da0250ba4dc0ed311931f1354430aaa3f651b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Ribaudo?= Date: Fri, 10 Jan 2020 21:26:52 +0100 Subject: [PATCH 3/5] Always use `.json` --- docs/cli.md | 4 +- docs/config-files.md | 62 ++++++++++++++--------------- docs/configuration.md | 8 ++-- docs/node.md | 2 +- docs/options.md | 36 ++++++++--------- docs/plugin-transform-typescript.md | 2 +- 6 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 8133855eb3..384c72968b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -137,9 +137,9 @@ Use the `--presets` option to specify presets to use in compilation npx babel script.js --out-file script-compiled.js --presets=@babel/preset-env,@babel/flow ``` -### Ignoring .babelrc.* +### Ignoring .babelrc.json -Ignore the configuration from the project's `.babelrc.*` file and use the cli options e.g. for a custom build +Ignore the configuration from the project's `.babelrc.json` file and use the cli options e.g. for a custom build ```sh npx babel --no-babelrc script.js --out-file script-compiled.js --presets=es2015,react diff --git a/docs/config-files.md b/docs/config-files.md index d469a9cf31..a0806b9528 100644 --- a/docs/config-files.md +++ b/docs/config-files.md @@ -8,15 +8,16 @@ id: config-files Babel has two parallel config file formats, which can be used together, or independently. * Project-wide configuration + * `babel.config.json` files, with the different extensions * File-relative configuration - * `.babelrc.*` files + * `.babelrc.json` files, with the different extensions * `package.json` files with a `"babel"` key ## Project-wide configuration New in Babel 7.x, Babel has a concept of a ["root"](options.md#root) directory, which defaults to the current working directory. For project-wide configuration, Babel will automatically search -for a `babel.config.*` file, using one of the [supported extensions](#supported-file-extensions), +for a `babel.config.json` file, or an equivalend one using the [supported extensions](#supported-file-extensions), in this root directory. Alternatively, users can use an explicit ["configFile"](options.md#configfile) value to override the default config file search behavior. @@ -33,7 +34,7 @@ Project-wide configs can also be disabled by setting ["configFile"](options.md#c ## File-relative configuration -Babel loads `.babelrc.*` files, using one of the [supported extensions](#supported-file-extensions), by searching up the +Babel loads `.babelrc.json` files, or an equivalend one using the [supported extensions](#supported-file-extensions), by searching up the directory structure starting from the ["filename"](options.md#filename) being compiled (limited by the caveats below). This can be powerful because it allows you to create independent configurations for subsections of a package. File-relative configurations are also [merged](options.md#merging) over top of @@ -47,12 +48,11 @@ There are a few edge cases to consider when using a file-relative config: ["babelrcRoots"](options.md#babelrcroots) packages, or else searching will be skipped entirely. These caveats mean that: -* `.babelrc.*` files _only_ apply to files within their own package -* `.babelrc.*` files in packages that aren't Babel's 'root' are ignored unless you opt in +* `.babelrc.json` files _only_ apply to files within their own package +* `.babelrc.json` files in packages that aren't Babel's 'root' are ignored unless you opt in with ["babelrcRoots"](options.md#babelrcroots). See the [monorepo](#monorepos) documentation for more discussion on how to configure monorepos that have many packages. - (and `.babelrc.js` / `.babelrc.cjs` / `package.json#babel`) File-relative configs can also be disabled by setting ["babelrc"](options.md#babelrc) to `false`. ### 6.x vs 7.x `.babelrc` loading @@ -88,14 +88,14 @@ Unfortunately, this approach can be a bit repetitive, and depending on how Babel could require setting ["babelrcRoots"](options.md#babelrcroots). Given that, it may be more desirable to rename the `.babelrc` to be a -[project-wide "babel.config.*"](#project-wide-configuration). As mentioned in the project-wide +[project-wide "babel.config.json"](#project-wide-configuration). As mentioned in the project-wide section above, this may then require explicitly setting ["configFile"](options.md#configfile) since Babel will not find the config file if the working directory isn't correct. ## Supported file extensions Babel can be configured using any file extension natively supported by Node.js: you can use `.json`, -`.js`, `.cjs` and `.mjs`, both for `babel.config.*` and `.babelrc.*` files. +`.js`, `.cjs` and `.mjs`, both for `babel.config.json` and `.babelrc.json` files. - `babel.config.json` and `.babelrc.json` are parsed as JSON5 and should contain an object matching the [options](options.md) format that Babel accepts. @@ -140,26 +140,26 @@ With monorepo setups, the core thing to understand is that Babel treats your wor as its logical ["root"](options.md#root), which causes problems if you want to run Babel tools within a specific sub-package without having Babel apply to the repo as a whole. -Separately, it is also important to decide if you want to use [`.babelrc.*`](#file-relative-configuration) -files or just a central [`babel.config.*`](#project-wide-configuration). [`.babelrc.*`](#file-relative-configuration) +Separately, it is also important to decide if you want to use [`.babelrc.json`](#file-relative-configuration) +files or just a central [`babel.config.json`](#project-wide-configuration). [`.babelrc.json`](#file-relative-configuration) files are not required for subfolder-specific configuration like they were in Babel 6, so often -they are not needed in Babel 7, in favor of [`babel.config.*`](#project-wide-configuration). +they are not needed in Babel 7, in favor of [`babel.config.json`](#project-wide-configuration). -### Root `babel.config.*` file +### Root `babel.config.json` file -The first step in any monorepo structure should be to create a [`babel.config.*`](#project-wide-configuration) +The first step in any monorepo structure should be to create a [`babel.config.json`](#project-wide-configuration) file in repository root. This establishes Babel's core concept of the base directory of your repository. -Even if you want to use [`.babelrc.*`](#file-relative-configuration) files to configure each separate package, +Even if you want to use [`.babelrc.json`](#file-relative-configuration) files to configure each separate package, it is important to have as a place for repo-level options. -You can often place all of your repo configuration in the root [`babel.config.*`](#project-wide-configuration). +You can often place all of your repo configuration in the root [`babel.config.json`](#project-wide-configuration). With ["overrides"](options.md#overrides), you can easily specify configuration that only applies to certain subfolders of your repository, which can often be easier to -follow than creating many `.babelrc.*` files across the repo. +follow than creating many `.babelrc.json` files across the repo. -The first issue you'll likely run into is that by default, Babel expects to load [`babel.config.*`](#project-wide-configuration) +The first issue you'll likely run into is that by default, Babel expects to load [`babel.config.json`](#project-wide-configuration) files from the directory set as its ["root"](options.md#root), which means that if you create -a [`babel.config.*`](#project-wide-configuration), but run +a [`babel.config.json`](#project-wide-configuration), but run Babel inside an individual package, e.g. ```bash @@ -167,17 +167,17 @@ cd packages/some-package; babel src -d dist ``` the ["root"](options.md#root) Babel is using in that context is _not_ your monorepo root, -and it won't be able to find the [`babel.config.*`](#project-wide-configuration) file. +and it won't be able to find the [`babel.config.json`](#project-wide-configuration) file. If all of your build scripts run relative to your repository root, things should already work, but if you are running your Babel compilation process from within a subpackage, you need to tell Babel where to look for the config. There are a few ways to do that, but the recommended way is the ["rootMode"](options.md#rootmode) option with `"upward"`, which will make Babel search from -the working directory upward looking for your [`babel.config.*`](#project-wide-configuration) file, +the working directory upward looking for your [`babel.config.json`](#project-wide-configuration) file, and will use its location as the ["root"](options.md#root) value. One helpful way to test if your config is being detected is to place a `console.log()` call -inside of it if it is a [`babel.config.*`](#project-wide-configuration) JavaScript file: the log will execute +inside of it if it is a [`babel.config.json`](#project-wide-configuration) JavaScript file: the log will execute the first time Babel loads it. How you set this value varies by project, but here are a few examples: @@ -232,14 +232,14 @@ There are tons of tools, but at the core of it is that they need the `rootMode` if the working directory is not already the monorepo root. -### Subpackage `.babelrc.*` files +### Subpackage `.babelrc.json` files -Similar to the the way [`babel.config.*`](#project-wide-configuration) files are required to be in the ["root"](options.md#root), -[`.babelrc.*`](#file-relative-configuration) files must be in the root _package_, by default. This means that, the same way the -working directory affects [`babel.config.*`](#project-wide-configuration) loading, it also affects [`.babelrc.*`](#file-relative-configuration) loading. +Similar to the the way [`babel.config.json`](#project-wide-configuration) files are required to be in the ["root"](options.md#root), +[`.babelrc.json`](#file-relative-configuration) files must be in the root _package_, by default. This means that, the same way the +working directory affects [`babel.config.json`](#project-wide-configuration) loading, it also affects [`.babelrc.json`](#file-relative-configuration) loading. -Assuming you've already gotten your [`babel.config.*`](#project-wide-configuration) file loaded properly as discussed above, -Babel will only process [`.babelrc.*`](#file-relative-configuration) files inside that root package (and not subpackages), +Assuming you've already gotten your [`babel.config.json`](#project-wide-configuration) file loaded properly as discussed above, +Babel will only process [`.babelrc.json`](#file-relative-configuration) files inside that root package (and not subpackages), so given for instance ```text @@ -252,10 +252,10 @@ packages/ index.js ``` compiling the `packages/mod/index.js` file will not load `packages/mod/.babelrc.json` because -this [`.babelrc.*`](#file-relative-configuration) is within a sub-package, not the root package. +this [`.babelrc.json`](#file-relative-configuration) is within a sub-package, not the root package. -To enable processing of that [`.babelrc.*`](#file-relative-configuration), you will want to use the ["babelrcRoots"](options.md#babelrcroots) -option from inside your [`babel.config.*`](#project-wide-configuration) file to do +To enable processing of that [`.babelrc.json`](#file-relative-configuration), you will want to use the ["babelrcRoots"](options.md#babelrcroots) +option from inside your [`babel.config.json`](#project-wide-configuration) file to do ```js babelrcRoots: [ @@ -263,7 +263,7 @@ babelrcRoots: [ "packages/*", ], ``` -so that Babel will consider all `packages/*` packages as allowed to load [`.babelrc.*`](#file-relative-configuration) files, +so that Babel will consider all `packages/*` packages as allowed to load [`.babelrc.json`](#file-relative-configuration) files, along with the original repo root. ## Config Function API diff --git a/docs/configuration.md b/docs/configuration.md index f8c0a11de0..640db0d821 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,15 +12,15 @@ All Babel API [options](options.md) are allowed. However, if the option requires - You are using a monorepo? - You want to compile `node_modules`? -> [`babel.config.*`](#babelconfigjs) is for you! +> [`babel.config.json`](#babelconfigjs) is for you! - You have a configuration that only applies to a single part of your project? -> [`.babelrc.*`](#babelrc) is for you! +> [`.babelrc.json`](#babelrc) is for you! - Guy Fieri is your hero? -> We recommend using the [`babel.config.*`](config-files.md#project-wide-configuration) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js). +> We recommend using the [`babel.config.json`](config-files.md#project-wide-configuration) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js). ### `babel.config.json` @@ -47,7 +47,7 @@ module.exports = function (api) { } ``` -Check out the [`babel.config.*` documentation](config-files.md#project-wide-configuration) to see more configuration options. +Check out the [`babel.config.json` documentation](config-files.md#project-wide-configuration) to see more configuration options. ### `.babelrc.json` diff --git a/docs/node.md b/docs/node.md index 289a953c69..9821796603 100644 --- a/docs/node.md +++ b/docs/node.md @@ -84,6 +84,6 @@ npx babel-node --debug --presets es2015 -- script.js --debug | `-x, --extensions` | `".js",".jsx",".es6",".es"` | List of extensions to hook into | | `--presets` | `[]` | Comma-separated list of [presets](presets.md) (a set of plugins) to load and use. | | `--plugins` | `[]` | Comma-separated list of [plugins](plugins.md) to load and use. | -| `--config-file [path]` | `[]` | Path to the babel config file to use. Defaults to working directory babel.config.* | +| `--config-file [path]` | `[]` | Path to the babel config file to use. Defaults to working directory babel.config.json | | `--env-name [name]` | `[]` | The name of the 'env' to use when loading configs and plugins. Defaults to the value of BABEL_ENV, or else NODE_ENV, or else 'development'. | diff --git a/docs/options.md b/docs/options.md index 8659ed876e..eef7fd7f23 100644 --- a/docs/options.md +++ b/docs/options.md @@ -71,7 +71,7 @@ The three primary cases users could run into are: * The filename is exposed to plugins. Some plugins may require the presence of the filename. * Options like [`"test"`](#test), [`"exclude"`](#exclude), and [`"ignore"`](#ignore) require the filename for string/RegExp matching. -* `.babelrc.*` files are loaded relative to the file being compiled. If this option is omitted, Babel will behave as if `babelrc: false` has been set. +* `.babelrc.json` files are loaded relative to the file being compiled. If this option is omitted, Babel will behave as if `babelrc: false` has been set. ### `filenameRelative` @@ -158,25 +158,25 @@ Babel can process the [`"root"`](#root) value to get the final project root. * `"root"` - Passes the [`"root"`](#root) value through as unchanged. * `"upward"` - Walks upward from the [`"root"`](#root) directory, looking - for a directory containing a [`babel.config.*`](config-files.md#project-wide-configuration) - file, and throws an error if a [`babel.config.*`](config-files.md#project-wide-configuration) + for a directory containing a [`babel.config.json`](config-files.md#project-wide-configuration) + file, and throws an error if a [`babel.config.json`](config-files.md#project-wide-configuration) is not found. * `"upward-optional"` - Walk upward from the [`"root"`](#root) directory, - looking for a directory containing a [`babel.config.*`](config-files.md#project-wide-configuration) - file, and falls back to [`"root"`](#root) if a [`babel.config.*`](config-files.md#project-wide-configuration) + looking for a directory containing a [`babel.config.json`](config-files.md#project-wide-configuration) + file, and falls back to [`"root"`](#root) if a [`babel.config.json`](config-files.md#project-wide-configuration) is not found. `"root"` is the default mode because it avoids the risk that Babel will -accidentally load a `babel.config.*` that is entirely outside of the current +accidentally load a `babel.config.json` that is entirely outside of the current project folder. If you use `"upward-optional"`, be aware that it will walk up the directory structure all the way to the filesystem root, and it is always -possible that someone will have a forgotten `babel.config.*` in their home +possible that someone will have a forgotten `babel.config.json` in their home directory, which could cause unexpected errors in your builds. Users with monorepo project structures that run builds/tests on a per-package basis -may well want to use `"upward"` since monorepos often have a [`babel.config.*`](config-files.md#project-wide-configuration) +may well want to use `"upward"` since monorepos often have a [`babel.config.json`](config-files.md#project-wide-configuration) in the project root. Running Babel in a monorepo subdirectory without `"upward"`, -will cause Babel to skip loading any [`babel.config.*`](config-files.md#project-wide-configuration) +will cause Babel to skip loading any [`babel.config.json`](config-files.md#project-wide-configuration) files in the project root, which can lead to unexpected errors and compilation failure. @@ -195,15 +195,15 @@ available inside configuration functions, plugins, and presets, via the ### `configFile` Type: `string | boolean`
-Default: `path.resolve(opts.root, "babel.config.*")`, if it exists, `false` otherwise
+Default: `path.resolve(opts.root, "babel.config.json")`, if it exists, `false` otherwise
Placement: Only allowed in Babel's programmatic options
-Defaults to searching for a default `babel.config.*` file, but can be passed +Defaults to searching for a default `babel.config.json` file, but can be passed the path of any JS or JSON5 config file. -NOTE: This option does _not_ affect loading of [`.babelrc.*`](config-files.md#file-relative-configuration) files, so while +NOTE: This option does _not_ affect loading of [`.babelrc.json`](config-files.md#file-relative-configuration) files, so while it may be tempting to do `configFile: "./foo/.babelrc.json"`, it is not recommended. -If the given [`.babelrc.*`](config-files.md#file-relative-configuration) is loaded via the standard +If the given [`.babelrc.json`](config-files.md#file-relative-configuration) is loaded via the standard file-relative logic, you'll end up loading the same config file twice, merging it with itself. If you are linking a specific config file, it is recommended to stick with a naming scheme that is independent of the "babelrc" name. @@ -221,7 +221,7 @@ to the [`"filename"`](#filename) provided to Babel. A `babelrc` value passed in the programmatic options will override one set within a configuration file. -Note: `.babelrc.*` files are only loaded if the current [`"filename"`](#filename) is inside of +Note: `.babelrc.json` files are only loaded if the current [`"filename"`](#filename) is inside of a package that matches one of the [`"babelrcRoots"`](#babelrcroots) packages. @@ -231,13 +231,13 @@ Type: `boolean | MatchPattern | Array`
Default: `opts.root`
Placement: Allowed in Babel's programmatic options, or inside of the loaded `configFile`. A programmatic option will override a config file one.
-By default, Babel will only search for `.babelrc.*` files within the [`"root"`](#root) package -because otherwise Babel cannot know if a given `.babelrc.*` is meant to be loaded, or +By default, Babel will only search for `.babelrc.json` files within the [`"root"`](#root) package +because otherwise Babel cannot know if a given `.babelrc.json` is meant to be loaded, or if it's [`"plugins"`](#plugins) and [`"presets"`](#presets) have even been installed, since the file being compiled could be inside `node_modules`, or have been symlinked into the project. This option allows users to provide a list of other packages that should be considered -"root" packages when considering whether to load `.babelrc.*` files. +"root" packages when considering whether to load `.babelrc.json` files. For example, a monorepo setup that wishes to allow individual packages to have their own configs might want to do @@ -247,7 +247,7 @@ babelrcRoots: [ // Keep the root as a root ".", - // Also consider monorepo packages "root" and load their .babelrc.* files. + // Also consider monorepo packages "root" and load their .babelrc.json files. "./packages/*" ] ``` diff --git a/docs/plugin-transform-typescript.md b/docs/plugin-transform-typescript.md index cf081a2bfc..3086bb10f8 100644 --- a/docs/plugin-transform-typescript.md +++ b/docs/plugin-transform-typescript.md @@ -199,7 +199,7 @@ equivalents in Babel can be enabled by some configuration options or plugins. - `--importHelpers` This is the equivalent of the `@babel/plugin-transform-runtime` package. - `--inlineSourceMap` - You can set the [`sourceMaps: "inline"`](https://babeljs.io/docs/en/options#sourcemaps) option in your `babel.config.*` file. + You can set the [`sourceMaps: "inline"`](https://babeljs.io/docs/en/options#sourcemaps) option in your `babel.config.json` file. - `--isolatedModules` This is the default Babel behavior, and it can't be turned off because Babel doesn't support cross-file analysis. - `--jsx` From 65a3796a6cea450a5cf6608799e23f1a4202d1ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Ribaudo?= Date: Fri, 10 Jan 2020 22:02:27 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-Authored-By: Brian Ng --- docs/config-files.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config-files.md b/docs/config-files.md index a0806b9528..6d07d10feb 100644 --- a/docs/config-files.md +++ b/docs/config-files.md @@ -17,7 +17,7 @@ Babel has two parallel config file formats, which can be used together, or indep New in Babel 7.x, Babel has a concept of a ["root"](options.md#root) directory, which defaults to the current working directory. For project-wide configuration, Babel will automatically search -for a `babel.config.json` file, or an equivalend one using the [supported extensions](#supported-file-extensions), +for a `babel.config.json` file, or an equivalent one using the [supported extensions](#supported-file-extensions), in this root directory. Alternatively, users can use an explicit ["configFile"](options.md#configfile) value to override the default config file search behavior. @@ -34,7 +34,7 @@ Project-wide configs can also be disabled by setting ["configFile"](options.md#c ## File-relative configuration -Babel loads `.babelrc.json` files, or an equivalend one using the [supported extensions](#supported-file-extensions), by searching up the +Babel loads `.babelrc.json` files, or an equivalent one using the [supported extensions](#supported-file-extensions), by searching up the directory structure starting from the ["filename"](options.md#filename) being compiled (limited by the caveats below). This can be powerful because it allows you to create independent configurations for subsections of a package. File-relative configurations are also [merged](options.md#merging) over top of @@ -100,7 +100,7 @@ Babel can be configured using any file extension natively supported by Node.js: - `babel.config.json` and `.babelrc.json` are parsed as JSON5 and should contain an object matching the [options](options.md) format that Babel accepts. - It is recommended to choose this file type wherever possible: JS config files are + We recommend using this file type wherever possible: JS config files are handy if you have complex configuration that is conditional or otherwise computed at build time. However, the downside is that JS configs are less statically analyzable, and therefore have negative effects on cacheability, linting, IDE autocomplete, etc. @@ -127,7 +127,7 @@ return the generated configuration. Function-returning configs are given a few special powers because they can access an API exposed by Babel itself. See [Config Function API](#config-function-api) for more information. -> For compatibility reasons, you could find `.babelrc` used as an alias for `.babelrc.json`. +> For compatibility reasons, `.babelrc` is an alias for `.babelrc.json`. ## Monorepos From 8ece6f8ae8bb8c3842cdae6976657186c71fb192 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Ribaudo?= Date: Fri, 10 Jan 2020 22:03:50 +0100 Subject: [PATCH 5/5] Review --- docs/config-files.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/config-files.md b/docs/config-files.md index 6d07d10feb..2141a00ef3 100644 --- a/docs/config-files.md +++ b/docs/config-files.md @@ -111,9 +111,7 @@ Babel can be configured using any file extension natively supported by Node.js: - `babel.config.cjs` and `.babelrc.cjs` allow you to define your configuration as CommonJS, using `module.exports`. -- `babel.config.mjs` and `.babelrc.mjs` use native ECMAScript modules. They are only supported by - Node.js 13.2 or newer, and might work in older versions when passing `--experimental-modules` flag - to Node.js. +- `babel.config.mjs` and `.babelrc.mjs` use native ECMAScript modules. They are supported by Node.js 13.2+ (or older versions via the `--experimental-modules` flag). Please remember that native ECMAScript modules are asynchronous (that's why `import()` always returns a promise!): for this reason, `.mjs` config files will throw when calling Babel synchronously.