Skip to main content

Canary releases

Docusaurus has a canary releases system.

It permits you to test new unreleased features as soon as the pull requests are merged.

It is a good way to give feedback to maintainers, ensuring the newly implemented feature works as intended.

note

Using a canary release in production might seem risky, but in practice, it's not.

A canary release passes all automated tests and is used in production by the Docusaurus site itself.

tip

The canary version shown below is directly fetched from npm and is up-to-date. You can directly use these numbers in your package.json.

Canary npm dist tag​

For any code-related commit on main, the continuous integration will publish a canary release under the @canary npm dist tag. It generally takes up to 10 minutes.

You can see on npm the current dist tags:

  • latest: stable releases (Current: 2.0.0-beta.21)
  • canary: canary releases (Current: 3.9.2-canary-6429)
tip

Make sure to use the latest canary release and check the publication date (sometimes the publish process fails). The latest canary version that's available on npm is published at 10/17/2025, 7:06:48 PM.

note

Canary versions follow the naming convention 0.0.0-commitNumber.

Using a canary release​

Take the latest version published under the canary npm dist tag (Current: 3.9.2-canary-6429).

Use it for all the @docusaurus/* dependencies in your package.json:

-  "@docusaurus/core": "^2.0.0-beta.21",
-  "@docusaurus/preset-classic": "^2.0.0-beta.21",
+  "@docusaurus/core": "3.9.2-canary-6429",
+  "@docusaurus/preset-classic": "3.9.2-canary-6429",

Then, install the dependencies again and start your site:

npm install
npm start

You can also upgrade the @docusaurus/* packages with command line:

npm install --save-exact @docusaurus/core@canary @docusaurus/preset-classic@canary
caution

Make sure to include all the @docusaurus/* packages.

For canary releases, prefer using an exact version instead of a semver range (avoid the ^ prefix).