Skip to content

5-canary.mdx

Latest commit

 

History

History
110 lines (69 loc) · 2.69 KB

5-canary.mdx

File metadata and controls

110 lines (69 loc) · 2.69 KB
Raw

Canary releases

import {
  VersionsProvider,
  CanaryVersion,
  StableVersion,
  InsertIfCanaryVersionUnknown,
  InsertIfCanaryVersionKnown,
  PackageJSONDiff,
  PublishTime,
} from "@site/src/components/Versions";

<VersionsProvider>

Docusaurus has a canary releases system.

It permits you to test new unreleased features as soon as the pull requests are merged on the next version of Docusaurus.

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.

:::

<InsertIfCanaryVersionUnknown>

:::caution

The canary version shown below may not be up-to-date. Please go to the npm page to find the actual version name.

:::

</InsertIfCanaryVersionUnknown>
<InsertIfCanaryVersionKnown>

:::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.

:::

</InsertIfCanaryVersionKnown>

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: )
  • canary: canary releases ()

:::tip

Make sure to use the latest canary release and check the publication date (sometimes the publish process fails).

:::

:::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 ().

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

<PackageJSONDiff />

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).

:::

</VersionsProvider>