Please improve documentation on how config options get merged

[mario-d-s]

Hi,

I was wondering how config options get merged between those passed to the JS API and those specified in config files (.babelrc, babel.config.js*). My question originally arose in rollup/rollup-plugin-babel#338 but I was told to report it here.

I found babel/babel#6765 and babel/babel#6905 but that seems to be more related to the env option... The documentation over at https://babeljs.io/docs/en/options#merging specifies how merging happens when using overrides. But I can't see how it gets merged between the JS API call to Babel (which is what tools like the Rollup plugin use) and the options it picks up from the various config files.

[babel-bot]

Hey @mario-d-s! We really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we're a limited number of volunteers, so it's possible this won't be addressed swiftly.

If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack community that typically always has someone willing to help. You can sign-up here for an invite."

[t47io]

+1 tagging on here, I had the following .babelrc:

{
  "plugins": [
    ["example", {
      "option1": "foo",
      "option2": "bar",
    }]
  ],
  "env": {
    "production": {
      "plugins": [
        ["example", {
          "option1": "baz"
        }]
      ]
    }
  }
}

I was expecting when running in production mode, the final babel config would have a single plugin with options merged, i.e.:

{ plugins: [ ['example', { option1: 'baz', option2: 'bar' }] ] }

But it does not. The behavior I'm observing is it's "overriding", not "merging". The current (@babel/core 7.8.3) gives:

{ plugins: [ ['example', { option1: 'baz' }] ] }

Just want to clarify the expectation, thanks!

[babel-bot]

Hey @mario-d-s! We really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we're a limited number of volunteers, so it's possible this won't be addressed swiftly.

If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack community that typically always has someone willing to help. You can sign-up here for an invite.

[thernstig]

@mario-d-s this is described here: https://babeljs.io/docs/en/configuration#print-effective-configs

@t47io this is described here: https://babeljs.io/docs/en/configuration#how-babel-merges-config-items

I think this issue can be closed. It is however good to know that there is an inconsistency in the descriptions of how merging works. I wrote a new issue about that here: https://github.com/babel/website/issues/2536