Skip to main content

Lançamentos canários

O Docusaurus possui um sistema de liberação canário.

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.

warning

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

Tag canário npm dist​

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: 3.10.2)
  • canary: canary releases (Exemplo: 0.0.0-4922)
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.

Usando um lançamento canário​

Take the latest version published under the canary npm dist tag (Exemplo: 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",

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
warning

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