feat: port to Redoc 3 (3.0.1)

.changeset/bright-routes-render.md

@@ -0,0 +1,26 @@
+---
+'docusaurus-plugin-redoc': major
+'docusaurus-theme-redoc': major
+'redocusaurus': major
+---
+
+feat!: upgrade to Redoc 3
+
+Redoc 3 replaces the Redoc 2 internals that redocusaurus was built on, so this is a major release. See the [migration guide](https://redocusaurus.vercel.app/docs/guides/migrating-to-v3).
+
+**Breaking changes**
+
+- Requires Node.js 22 or newer (Redoc 3 needs it), and `react` and `react-dom` 18.3 or newer are now peer dependencies of the preset and the theme (they are already in every Docusaurus site). `react-router` 7 is installed next to the version Docusaurus uses, for Redoc.
+- Redoc 3 routes by path, not by hash: `#tag/Pets/operation/addPet` is now `<route>/pets/addpet`. Old `#tag/...` links are redirected in the browser, but `#operation/<id>`, `#section/...` and `#schema/...` are not, and links in your own docs should be updated.
+- `@theme/ApiOperation` and `@theme/ApiSchema` are removed, and so are the `ServerRedoc` and `ServerStyles` theme components.
+- The Redoc 2 `theme` object (the `theme` option, and `theme.openapi.theme` in `redocly.yaml`) is ignored, because Redoc 3 is themed with CSS variables. A warning is printed once at build time.
+- Redoc's usage telemetry is turned off by default (`disableTelemetry: true`). Set `disableTelemetry: false` to turn it back on.
+- Redoc 3 has its own configuration reference, so review your `options` and the `theme.openapi` section of `redocly.yaml` against it.
+
+**New**
+
+- Every tag and operation is rendered to its own static page at build time, with one exact route each. Unknown paths below an API's route are a 404, links to them are checked when you build, and no server fallback rule is needed. The new `ssr` option (preset or spec) is `true` by default, `'required'` fails the build if it cannot render, and `false` turns it off. Production builds only, default locale only.
+- The API pages follow your Docusaurus theme (fonts, colors, light and dark mode) by default. `primaryColor` and `primaryColorDark` accept any CSS color, and the new `cssVariables: { light, dark }` option sets any other Redoc variable.
+- A new `syncColorMode` theme option (default `true`) keeps Redoc's light and dark mode in step with Docusaurus's, switching Redoc in place without rebuilding the page (so it keeps its scroll position). Redoc 3 has no option for this, so it relies on how Redoc stores its mode; set it to `false` to let Redoc follow its own mode.
+- Swagger 2.0 specs are converted by Redoc 3 when the page renders.
+- Whitespace around an `operationId` is trimmed, with a warning naming the operation.

.eslintrc

@@ -68,6 +68,13 @@
       "rules": {
         "@typescript-eslint/explicit-function-return-type": "off"
       }
+    },
+    {
+      "files": ["packages/*/test/**/*.js"],
+      "rules": {
+        "@typescript-eslint/no-var-requires": "off",
+        "max-lines": "off"
+      }
     }
   ]
 }

.github/workflows/build.yml

@@ -39,6 +39,9 @@ jobs:
       - name: Build Packages 🔨
         run: yarn build:packages
 
+      - name: Unit Tests 🧪
+        run: yarn test:unit
+
       - name: Build Website 🔨
         run: yarn build:website
         env:

DEVELOPMENT.md

@@ -28,6 +28,17 @@ This repository is structured as a [monorepo](https://blog.npmjs.org/post/186494
    yarn dev:website
    ```
 
+## Tests
+
+The unit tests are in `packages/*/test` and use Node's built-in test runner (Node 22 or newer), without any extra dependency. They test the built files in `dist`, so build the packages first:
+
+```sh
+yarn build:packages
+yarn test:unit
+```
+
+Some of them render a small spec with the real Redoc 3, so they take a few seconds. The visual end-to-end tests of the website are separate (`yarn test` in `website`).
+
 ## Releasing
 
 Releases, versioning and Changelogs are handled by [changesets](./.changeset/README.md).

README.md

@@ -10,6 +10,8 @@
 
 [Redoc](https://github.com/redocly/redoc) for [Docusaurus](https://docusaurus.io/).
 
+Redocusaurus renders your OpenAPI specs with Redoc 3, and needs Node.js 22 or newer. Coming from Redoc 2? See the [migration guide](https://redocusaurus.vercel.app/docs/guides/migrating-to-v3).
+
 ## Usage
 
 Check the [documentation on the website](https://redocusaurus.vercel.app/docs)
@@ -26,11 +28,11 @@ A Docusaurus Preset that combines the below 2 packages to easily add API doc(s)
 
 ### [Docusaurus Theme Redoc](./packages/docusaurus-theme-redoc)
 
-A wrapper around `RedocStandalone` to make it match the Docusaurus Theme with added support for Dark Mode.
+A wrapper around Redoc 3's `RedocStandalone` to make it follow the Docusaurus Theme (light and dark mode, fonts and colors), with path-based deep links.
 
 ### [Docusaurus Plugin Redoc](./packages/docusaurus-plugin-redoc)
 
-A content plugin that creates pages from your OpenAPI files or URLs and renders them using the Redoc component from the theme.
+A content plugin that creates pages from your OpenAPI files or URLs, renders every tag and operation to static HTML at build time, and hands the spec to the Redoc component from the theme in the browser.
 
 ### [Website](./website)