Skip to main content

Versions Canary

Docusaurus a un système de versions canary.

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.

remarque

Utiliser une version canary en production peut sembler risqué, mais en pratique, ce n'est pas le cas.

Une version canary passe tous les tests automatisés et est utilisée en production par le site Docusaurus lui-même.

attention

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

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. Cela prend généralement jusqu'à 10 minutes.

You can see on npm the current dist tags:

  • latest: stable releases (Current: 3.10.2)
  • canary: canary releases (Exemple : 0.0.0-4922)
astuce

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

remarque

Canary versions follow the naming convention 0.0.0-commitNumber.

Utilisation d'une version canary​

Take the latest version published under the canary npm dist tag (Exemple : 0.0.0-4922).

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

-  "@docusaurus/core": "^3.10.2",
-  "@docusaurus/preset-classic": "^3.10.2",
+  "@docusaurus/core": "0.0.0-4922",
+  "@docusaurus/preset-classic": "0.0.0-4922",

Ensuite, réinstallez les dépendances et démarrez votre 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
attention

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

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

package manager security

Some package managers have security options enabled by default to mitigate supply chain attacks, notably requiring npm packages to reach a minimum age.

To ensure the most recent canary release can install successfully, try the following options env variables:

# npm
# if it doesn't work, try "npm_config_min_release_age=0"
# see https://github.com/facebook/docusaurus/pull/12437
npm_config_min_release_age_exclude='create-docusaurus,@docusaurus/*'

# pnpm
PNPM_CONFIG_MINIMUM_RELEASE_AGE_EXCLUDE='["create-docusaurus","@docusaurus/*"]'

# Yarn Berry
yarn config set --json npmPreapprovedPackages '["create-docusaurus","@docusaurus/*"]'

Creating a new canary website​

Here's a full example script to initialize a new Docusaurus site with our most recent canary release:

PNPM_CONFIG_MINIMUM_RELEASE_AGE_EXCLUDE='["create-docusaurus","@docusaurus/*"]' pnpm dlx create-docusaurus@canary my-canary-website classic --typescript

cd my-canary-website

pnpm config set --location=project --json minimumReleaseAgeExclude '["create-docusaurus","@docusaurus/*"]'
pnpm config set --location=project --json allowBuilds '{"@swc/core":false,"core-js":false}'
pnpm install

pnpm build