From aa77cefcddf6e3ded50ece86e185dc0ad60f52ee 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] Always use --- 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`