Why is the version of docusaurus hardcoded in package.json?

[codayon]

When I first initialized a Docusaurus project, there was a bug (#11232). Now that Docusaurus has released version 3.9 with fixes, I tried to upgrade my packages using pnpm update, but it didn’t solve the issue because the version was hardcoded in package.json. Then I tried manually editing that file, and it did update, although the issue was not completely resolved.

[codayon]

This is how newly initialized docusaurus package.json looks like,

{
  "name": "my-website",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "3.9.1",
    "@docusaurus/preset-classic": "3.9.1",
    "@mdx-js/react": "^3.0.0",
    "clsx": "^2.0.0",
    "prism-react-renderer": "^2.3.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "3.9.1",
    "@docusaurus/types": "3.9.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  },
  "engines": {
    "node": ">=20.0"
  }
}

[slorber]

We prefer fixed versions instead of semver version ranges because we require our Docusaurus version packages to all be strictly aligned (ie you can't mix v3.9.0 and v3.9.1 packages), because we do not guarantee perfect interoperability between packages using different versions).

From what I remember, in the past, we had various bug reports where users inadvertently used different versions, leading to very weird runtime failures that were hard to troubleshoot.

The bug you mention is still not fixed in v3.9, see my comment here: #11232 (comment)