Skip to content

Commit

Permalink
Always use
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicolo-ribaudo
nicolo-ribaudo committed Jan 10, 2020
1 parent 770d95a commit aa77cef
Show file tree
Hide file tree
Showing 6 changed files with 57 additions and 57 deletions.
4 changes: 2 additions & 2 deletions docs/cli.md
View file
Expand Up @@ -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
Expand Down
62 changes: 31 additions & 31 deletions docs/config-files.md
View file
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -140,44 +140,44 @@ 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
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:
Expand Down Expand Up @@ -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
Expand All @@ -252,18 +252,18 @@ 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: [
".",
"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
Expand Down
8 changes: 4 additions & 4 deletions docs/configuration.md
View file
Expand Up @@ -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`

Expand All @@ -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`

Expand Down
2 changes: 1 addition & 1 deletion docs/node.md
View file
Expand Up @@ -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'. |

36 changes: 18 additions & 18 deletions docs/options.md
View file
Expand Up @@ -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`
Expand Down Expand Up @@ -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.


Expand All @@ -195,15 +195,15 @@ available inside configuration functions, plugins, and presets, via the
### `configFile`

Type: `string | boolean`<br />
Default: `path.resolve(opts.root, "babel.config.*")`, if it exists, `false` otherwise<br />
Default: `path.resolve(opts.root, "babel.config.json")`, if it exists, `false` otherwise<br />
Placement: Only allowed in Babel's programmatic options<br />

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.
Expand All @@ -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.


Expand All @@ -231,13 +231,13 @@ Type: `boolean | MatchPattern | Array<MatchPattern>`<br />
Default: `opts.root`<br />
Placement: Allowed in Babel's programmatic options, or inside of the loaded `configFile`. A programmatic option will override a config file one.<br />

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
Expand All @@ -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/*"
]
```
Expand Down

0 comments on commit aa77cef

Please sign in to comment.