---
description: Notable changes between Mocha 12 RC 1 and 11.7.4.
title: Mocha 12 RC 1 is here!
date: 2026-06-20T16:00:00Z
excerpt: "Mocha 12 is the first release to follow our
  [even-odd major release pattern](https://github.com/mochajs/mocha/blob/main/MAINTAINERS.md#major-releases).
  As an even release, Mocha 12 introduces very few breaking changes:
  We've bumped our Node floor, removed some long-deprecated features,
  and modernized a bit, but everything else works just as before."
---

import { PackageManagers } from "starlight-package-managers";

Mocha 12 is the first release to follow our
[even-odd major release pattern](https://github.com/mochajs/mocha/blob/main/MAINTAINERS.md#major-releases).
As an even release, Mocha 12 introduces very few breaking changes:
We've bumped our Node floor, removed some long-deprecated features,
and modernized a bit, but everything else works just as before.

These notes cover all changes in our first release candidate, `12.0.0-rc.1`. The baseline is `11.7.4`, after which we started releasing betas. To view the full changelog, see [CHANGELOG.md on Github](https://github.com/mochajs/mocha/blob/main/CHANGELOG.md).

As a release candidate, RC 1 contains all the features that will be in `12.0.0`. We will work to fix bugs for future release candidates, then release a stable `12.0.0` when it's ready.

We will continue to support critical bugfixes in Mocha 11 while customers upgrade to Mocha 12. We've also deployed [v11.mochajs.org](https://v11.mochajs.org) for users that may rely on Mocha 11 in the long-term.

You can try the RC now with a standard install:

<PackageManagers dev type="add" pkg="mocha@12.0.0-rc.1" />

<a id="breaking-changes"></a>

## Breaking changes

- [Bump minimum Node.js version from 18.18.0 to 20.19.0 and 22.12.0
  (#5477)](https://github.com/mochajs/mocha/issues/5477):
  We know that Node 20 is now EOL,
  but we didn't want to jump 2 LTS versions in one release.
  Mocha 13 will drop support for Node 20.
  The new minimum versions are the lowest Node versions that support `require(esm)`
  (see [internal modernization](#internal-modernization)).
- [Remove `util.inherits` / convert to classes
  (#5025)](https://github.com/mochajs/mocha/issues/5025):
  Through Mocha 11, reporters inherited behavior through `util.inherits`.
  This was deprecated a long time ago.
  Reporters now inherit through canonical `class` syntax.
  This means that the syntax for custom reporters has changed,
  but the core behavior is the same. See the updated
  [third-party reporters](https://mochajs.org/explainers/third-party-reporters/)
  page for details.
- [Remove `bin/_mocha` and convert `bin/` and entry points to ESM
  (#6017)](https://github.com/mochajs/mocha/pull/6017):
  The `_mocha` entry point had been kept as a workaround for old coverage providers.
  Swapping `path/to/_mocha` with `mocha` should work without issue.
- [Change root `package.json` type to `module`
  (#6078)](https://github.com/mochajs/mocha/pull/6078):
  This should not be a breaking change for the vast majority of users,
  see [internal modernization](#internal-modernization).
- [Change the default of `--forbid-only` to check for process.env.CI
  (#5496)](https://github.com/mochajs/mocha/issues/5496):
  This should improve CI runs, but rare use-cases may need to
  explicitly set `--no-forbid-only` to restore the previous default behavior.
- [Remove unused legacy `errors.js` functions
  (#5835)](https://github.com/mochajs/mocha/pull/5835):
  The public function `createInvalidPluginError` has been deprecated for years.
  Callers should use `createInvalidLegacyPluginError` instead,
  which has the exact same contract and behavior.
- [Cleanup references of `--compilers`
  (#5403)](https://github.com/mochajs/mocha/issues/5403):
  This flag had been deprecated for a long time.
  It had not had any impact on behavior for years.
  It is now removed from the codebase.

## Notable new features

- [Allow FIFOs as test files (#5512)](https://github.com/mochajs/mocha/issues/5512)
- [Add mocha.mjs export (#5527)](https://github.com/mochajs/mocha/issues/5527):
  This has since been renamed `mocha.js` but it still works for use in the browser!
- [Add `--fail-hook-affected-tests` option to report skipped tests as failed
  (#5519)](https://github.com/mochajs/mocha/issues/5519)

## Notable fixes

- [Allow importing ESM interface and reporters (#5563)](https://github.com/mochajs/mocha/issues/5563)
- [Support file: URLs in loadFilesAsync (#5833)](https://github.com/mochajs/mocha/pull/5833)
- [Support modern RegExp flags in Mocha#grep (#5825)](https://github.com/mochajs/mocha/pull/5825)
- [Prevent diff hang on large/complex objects (#5898)](https://github.com/mochajs/mocha/pull/5898)
- [Surface global setup/teardown errors with a non-zero exit code (#5994)](https://github.com/mochajs/mocha/pull/5994)

<a id="internal-modernization"></a>

## Internal modernization

- As mentioned in [breaking changes](#breaking-changes),
  Mocha is now an ESM-first package,
  using `"type": "module"` instead of `"type": "commonjs"` in `package.json`.
  This should not be a breaking change for the vast majority of users;
  CJS consumers can still `require('mocha')` just as before,
  thanks to new support in Node 20.19.0 and 22.12.0.
  We've marked it as "breaking" for users that depend on
  Mocha's internal structure for any reason.
  ESM is the modern, canonical way of managing modules,
  supported officially by the ECMAScript spec.
  CJS was always a placeholder approach until a better solution came along.
  ([#5400](https://github.com/mochajs/mocha/issues/5400))
- Mocha now uses Playwright instead of Karma for its internal tests.
  This is not a user-facing change in any way,
  but it means that Mocha contributors can now use
  a modern browser automation library instead of
  the long-deprecated Karma approach.
  This will help us better support browser-based testing in the future.
  ([#6031](https://github.com/mochajs/mocha/pull/6031))

## Thank you!

Mocha development could not continue without the support of contributors
who have opened issues, submitted PRs, and commented in discussions.
98 merged PRs for Mocha 12 were
[opened by community members](https://github.com/search?q=repo%3Amochajs%2Fmocha+is%3Apr+is%3Amerged+merged%3A2025-10-02..2026-06-18+-author%3Amark-wiemer+-author%3Ajoshuakgoldberg+-author%3Avoxpelli+-author%3Arenovate%5Bbot%5D+-author%3Agithub-actions%5Bbot%5D+-author%3Adependabot%5Bbot%5D&type=pullrequests&s=updated&o=desc)!
We are also very grateful to our many
[financial donors](https://opencollective.com/mochajs).

Mocha continues to thrive thanks to all of these generous contributions.
Thank you.

## Questions, comments, concerns?

As always, you can
[open an issue on GitHub](https://github.com/mochajs/mocha/issues?q=sort%3Aupdated-desc+is%3Aissue+state%3Aopen+)
or [message us on Discord](https://discord.gg/KeDn2uXhER) for support 🤎

## References

- [CHANGELOG.md](https://github.com/mochajs/mocha/blob/main/CHANGELOG.md)
