Skip to content

Conversation

@adamziel
Copy link
Collaborator

@adamziel adamziel commented Nov 15, 2025

Motivation for the change, related issues

Resolves a crash in the API reference that happened after the initial page hydration:

CleanShot 2025-11-14 at 15 03 22@2x

Implementation details

Problem 1 – CommonJS bundles from the TypeDoc plugin

docusaurus-plugin-typedoc-api ships its React components as CommonJS (module.exports = ApiPage). When Docusaurus’ ComponentCreator hydrates a page, it copies every enumerable export from the module onto the component. CommonJS functions still expose length, which is non‑writable, so the assignment throws Cannot assign to read only property 'length'.

Solution: Our wrapper plugin (packages/docs/site/plugins/typedoc-api-wrapper.js) intercepts the routes the TypeDoc plugin adds and swaps each component path for an ESM wrapper in packages/docs/site/src/typedoc/*.tsx. An ESM re‑export only exposes default, so ComponentCreator never tries to overwrite length and hydration succeeds.

Problem 2 – duplicate Docusaurus contexts

The TypeDoc plugin pulls its own copy of @docusaurus/plugin-content-docs (and friends). Webpack bundles that second copy, so components inside the API reference end up reading from a different React context than the one the rest of the site provides, leading to Hook useDocsPreferredVersionContext is called outside… errors.

Solution: packages/docs/site/plugins/docusaurus-dedupe-aliases.js walks each package’s exports map and tells Webpack to resolve every @docusaurus/* import to the single, hoisted version. With only one copy of the docs plugin, the contexts align and DocSearch/TypeDoc stop crashing.

Testing Instructions (or ideally a Blueprint)

This PR adds a dedicated Playwright config and test that builds the docs site, serves the static bundle, loads /wordpress-playground/api, and fails if hydration throws page or console errors. A new Nx target and CI job run the smoke test with Chromium so every PR proves the API docs render before we deploy.

The API reference had been crashing after hydration because we relied on CJS component shims that loaded a second copy of the docs plugin contexts. We already patched the runtime and aliased Docusaurus to fix the bug, but there was nothing preventing regressions. This commit adds a dedicated Playwright config and test that builds the docs site, serves the static bundle, loads /wordpress-playground/api, and fails if hydration throws page or console errors. A new Nx target and CI job run the smoke test with Chromium so every PR proves the API docs render before we deploy.
@adamziel adamziel added [Type] Bug An existing feature does not function as intended [Type] Documentation Improvements or additions to documentation labels Nov 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Bug An existing feature does not function as intended [Type] Documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants