Conflicting documentation about preset-env's bugfixes option in v8 migration

[gilmoreorless]

💻

• Would you like to work on a fix?

How are you using Babel?

Programmatic API (babel.transform, babel.parse)

Input code

Any code; this is a config issue

Configuration file name

No response

Configuration

No response

Current and expected behavior

I've been testing an upgrade to Babel 8 beta and found a confusing conflict around one of the options. The migration guide for Babel 8 currently says this in the "Getting ready" section, for changes to make while still using version 7:

If you use @babel/preset-env, enable its bugfixes option.

I did this using 7.28.3 and it ran fine. I then updated to 8.0.0-beta.2 and got the following error when calling Babel:

Error: [BABEL] /path/to/file.js: @babel/preset-env: The 'bugfixes' option has been removed, and now bugfix plugins are always enabled. Please remove it from your config.

In my project, I'm using the babel API programmatically without a separate config file. So I also tried this (and got the same result) on a minimal reproduction repo, with a babel.config.json that contains only the preset-env config:

{
  "presets": [
    ["@babel/preset-env", {
      "bugfixes": true
    }]
  ]
}

I only added that option because the migration guide said to. The latest documentation for that option says that it was added in 7.9.0, defaulting to true. But there's no indication that the option has been removed.

Environment

• Node 22.19.0
• Babel 7.28.3 and 8.0.0-beta.2
• pnpm 9.15.9 and 10.15.1
• macOS 15.6.1

Possible solution

My suggestions:

1. Since the option defaults to true, maybe tweak the wording in the upgrade guide to say it only needs changing if it's explicitly disabled.
2. Update the Babel 8 documentation to note that the option has been removed.

Additional context

No response

[babel-bot]

Hey @gilmoreorless! 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.

[babel-bot]

Hey @gilmoreorless! 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.

[JLHwung]

Thank you for opening the issue. This issue will be fixed in #3129.