docs: refine Babel config merging strategies #2531
Conversation
|
Deploy preview for babel ready! Built with commit f81c02c |
|
✔️ Deploy Preview for babel ready! 🔨 Explore the source changes: 963a15d 🔍 Inspect the deploy log: https://app.netlify.com/sites/babel/deploys/60b0ec7caa415700076b79e8 😎 Browse the preview: https://deploy-preview-2531--babel.netlify.app |
docs/configuration.md
Outdated
| For each config items mentioned above, Babel applies `Object.assign` on options except for `plugins` and `presets`, which is concatenated by `Array#concat`. For example | ||
| For each config items mentioned above, Babel applies `Object.assign` on the option object, which means the option value will be overwritten by another one with higher priority. However, the following options have specialized strategies: | ||
|
|
||
| - for `plugins` and `presets`, Babel merge them by `Array#concat`. |
There was a problem hiding this comment.
| - for `plugins` and `presets`, Babel merge them by `Array#concat`. | |
| - for `plugins` and `presets`, Babel merges them via `Array#concat`. |
docs/configuration.md
Outdated
| For each config items mentioned above, Babel applies `Object.assign` on the option object, which means the option value will be overwritten by another one with higher priority. However, the following options have specialized strategies: | ||
|
|
||
| - for `plugins` and `presets`, Babel merge them by `Array#concat`. | ||
| - for `parserOpts`, `generatorOpts` and `assumptions`, Babel merge them by `Object.assign` |
There was a problem hiding this comment.
| - for `parserOpts`, `generatorOpts` and `assumptions`, Babel merge them by `Object.assign` | |
| - for `parserOpts`, `generatorOpts` and `assumptions`, Babel merges them via `Object.assign` |
|
I didn't realize we already have option merging docs on https://babeljs.io/docs/en/options#merging, thanks to @thernstig who points it out. Since the @thernstig Can you take a review if it resolves #2536? The preview link is here. |
docs/configuration.md
Outdated
| Babel's configuration merging is relatively straightforward. Options will overwrite existing options | ||
| when they are present, and their value is not `undefined`, with a few special cases: | ||
|
|
||
| - For `assumptions`, `parserOpts` and `generatorOpts`, objects are merged, rather than replaced, using the same logic as top-level options. |
There was a problem hiding this comment.
using the same logic as top-level options.
I don't think that logic has been explained anywhere else. But since the first part of the sentence says objects are merged, maybe this part is superfluous?
The confusion for me is that the options you list are themselves "top-level options": https://babeljs.io/docs/en/options
| @@ -196,34 +198,99 @@ If your input is ignored by `ignore` or `only`, Babel will print that this file | |||
|
|
|||
| ### How Babel merges config items | |||
There was a problem hiding this comment.
This headline is called "How babel merges config items". But config items are "Options" in my world: https://babeljs.io/docs/en/options
Then later there is now a new headline "Options merging"
This makes it confusing to the reader. as the entire chapter is about options merging. Note that presets and plugins are also options, as indicated by the headline here: https://babeljs.io/docs/en/options#plugin-and-preset-options
docs/configuration.md
Outdated
| }; | ||
| ``` | ||
|
|
||
| When `NODE_ENV` is `test`, the `test` item will be merged on top of the top-level plugins. |
There was a problem hiding this comment.
top-level plugins
Mistake?
| } | ||
| ``` | ||
|
|
||
| #### Plugin/Preset merging |
There was a problem hiding this comment.
Plugin and presets are also options: https://babeljs.io/docs/en/options
So the above "Options merging" makes this headline readers confused as everything described in this chapter are "Options". (This is the same comment as the ones above in a sense.)
There was a problem hiding this comment.
Yeah, the intention is options except plugins/presets. A config item in @babel/core have plugins, presets and options. But yeah you are right, we should figure out a new term.
| ``` | ||
|
|
||
| because each instance has been given a unique name and this a unique identity. | ||
| Please refer to [How Babel merges config items](configuration.md#how-babel-merges-config-items). |
Co-authored-by: Brian Ng <bng412@gmail.com>
|
LGTM 👍 |
I realize that we didn't mention how we merge
parserOpts,generatorOptsandassumptions. This PR documents current merging strategies and updates the examples.Preview
Resolves #2536