[Docs] Fix API reference (#2905)

## Motivation for the change, related issues

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

<img width="2138" height="1232" alt="CleanShot 2025-11-14 at 15 03
22@2x"
src="https://github.com/user-attachments/assets/2602a5e8-29e3-4342-aefc-b52b0b858bad"
/>

It also ships E2E tests just for the documentation site.

## 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.

Author: adamziel

.github/workflows/ci.yml

@@ -169,6 +169,19 @@ jobs:
     test-e2e-playwright-prepare:
         runs-on: ubuntu-latest
         steps:
+            - name: Free up runner disk space
+              shell: bash
+              run: |
+                  set -euo pipefail
+                  echo "Disk usage before cleanup:"
+                  df -h
+                  sudo rm -rf /usr/local/lib/android
+                  sudo rm -rf /usr/share/dotnet
+                  sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+                  sudo rm -rf /opt/ghc
+                  sudo rm -rf /opt/hostedtoolcache/CodeQL
+                  echo "Disk usage after cleanup:"
+                  df -h
             - uses: actions/checkout@v4
               with:
                   submodules: true
@@ -254,6 +267,18 @@ jobs:
                   path: packages/playground/components/playwright-report/
                   if-no-files-found: ignore
 
+    test-docs-api-reference:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  submodules: true
+            - uses: ./.github/actions/prepare-playground
+            - name: Install Playwright Browsers
+              run: npx playwright install --with-deps chromium
+            - name: Verify docs API reference
+              run: npx nx run docs-site:api-e2e
+
     test-built-npm-packages:
         runs-on: ubuntu-latest
         steps:

package-lock.json

@@ -79,6 +79,8 @@
 		"@codemirror/search": "6.5.11",
 		"@codemirror/state": "6.5.2",
 		"@codemirror/view": "6.38.3",
+		"@docusaurus/plugin-content-docs": "3.9.2",
+		"@docusaurus/theme-common": "3.9.2",
 		"@preact/signals-react": "1.3.6",
 		"@reduxjs/toolkit": "2.6.1",
 		"@types/xml2js": "0.4.14",

package.json

@@ -25,11 +25,7 @@ const config = {
 	projectName: 'wordpress-playground', // Usually your repo name.
 
 	onBrokenLinks: 'throw',
-	markdown: {
-		hooks: {
-			onBrokenMarkdownLinks: 'throw',
-		},
-	},
+	onBrokenMarkdownLinks: 'throw',
 
 	// Even if you don't use internalization, you can use this field to set useful
 	// metadata like HTML lang. For example, if your site is Chinese, you may want
@@ -71,6 +67,7 @@ const config = {
 	},
 	themes: ['@docusaurus/theme-live-codeblock'],
 	plugins: [
+		'./plugins/docusaurus-dedupe-aliases.js',
 		getDocusaurusPluginTypedocApiConfig(),
 		[
 			'@docusaurus/plugin-ideal-image',
@@ -266,7 +263,7 @@ function getDocusaurusPluginTypedocApiConfig() {
 	};
 
 	return [
-		'docusaurus-plugin-typedoc-api',
+		require.resolve('./plugins/typedoc-api-wrapper.js'),
 		{
 			projectRoot,
 			packages,

packages/docs/site/docusaurus.config.js

@@ -0,0 +1,59 @@
+import { defineConfig } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+const port = process.env.DOCS_E2E_PORT ?? '4173';
+const host = process.env.DOCS_E2E_HOST ?? '127.0.0.1';
+const baseUrl = process.env.DOCS_E2E_BASE_URL ?? `http://${host}:${port}`;
+const rawBasePath = process.env.DOCS_E2E_BASE_PATH ?? '/wordpress-playground';
+const normalizedBasePath =
+	rawBasePath === '/' ? '/' : `/${rawBasePath.replace(/^\/|\/$/g, '')}`;
+const healthPath =
+	process.env.DOCS_E2E_HEALTH_PATH ?? `${normalizedBasePath}/index.html`;
+const repoRoot =
+	process.env.DOCS_E2E_REPO_ROOT ?? path.resolve(__dirname, '../../..');
+const buildDir =
+	process.env.DOCS_E2E_BUILD_DIR ?? path.join(repoRoot, 'dist/docs/build');
+
+const mountDir =
+	normalizedBasePath === '/'
+		? null
+		: path.join(buildDir, normalizedBasePath.replace(/^\//, ''));
+
+if (mountDir && fs.existsSync(buildDir) && !fs.existsSync(mountDir)) {
+	try {
+		fs.symlinkSync(buildDir, mountDir, 'junction');
+	} catch (error) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			`docs-site e2e: failed to create symlink for base path ${normalizedBasePath}`,
+			error
+		);
+	}
+}
+
+export default defineConfig({
+	testDir: './tests',
+	timeout: 60_000,
+	expect: {
+		timeout: 10_000,
+	},
+	use: {
+		baseURL: baseUrl,
+		trace: 'retain-on-failure',
+		screenshot: 'only-on-failure',
+		video: 'retain-on-failure',
+	},
+	webServer: {
+		command: `npx http-server "${buildDir}" -p ${port} -a ${host} -c-1`,
+		url: `${baseUrl}${healthPath}`,
+		reuseExistingServer: !process.env.CI,
+		timeout: 120_000,
+	},
+	projects: [
+		{
+			name: 'chromium',
+			use: { browserName: 'chromium' },
+		},
+	],
+});

packages/docs/site/playwright.config.ts

@@ -0,0 +1,132 @@
+const fs = require('fs');
+const path = require('path');
+const moduleRequire = require('module').createRequire(__dirname);
+
+const PACKAGES_TO_DEDUPE = [
+	'@docusaurus/plugin-content-docs',
+	'@docusaurus/theme-common',
+	'@docusaurus/theme-search-algolia',
+];
+
+function getExportKeys(exportsField) {
+	if (!exportsField) {
+		return ['.'];
+	}
+
+	if (typeof exportsField === 'string') {
+		return ['.'];
+	}
+
+	if (Array.isArray(exportsField)) {
+		return ['.'];
+	}
+
+	if (typeof exportsField === 'object') {
+		const keys = new Set(['.']);
+		for (const key of Object.keys(exportsField)) {
+			if (key === 'default' || key.includes('*')) {
+				continue;
+			}
+			keys.add(key);
+		}
+		return Array.from(keys);
+	}
+
+	return ['.'];
+}
+
+function normalizeSubpath(pkgName, subpath) {
+	if (subpath === '.' || !subpath) {
+		return pkgName;
+	}
+	return `${pkgName}/${subpath.replace(/^\.\//, '')}`;
+}
+
+function resolvePackageMetadata(pkgName) {
+	let entryPoint;
+	try {
+		entryPoint = moduleRequire.resolve(pkgName);
+	} catch (error) {
+		console.warn(
+			`docusaurus-dedupe-aliases: unable to resolve entry for ${pkgName}`,
+			error
+		);
+		return null;
+	}
+
+	let currentDir = path.dirname(entryPoint);
+	const fsRoot = path.parse(currentDir).root;
+
+	while (currentDir && currentDir !== fsRoot) {
+		const candidate = path.join(currentDir, 'package.json');
+		if (fs.existsSync(candidate)) {
+			const pkgJson = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+			if (pkgJson?.name === pkgName) {
+				return { pkgJson, pkgRoot: currentDir };
+			}
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	console.warn(
+		`docusaurus-dedupe-aliases: could not locate package.json for ${pkgName}`
+	);
+	return null;
+}
+
+function buildAliasesForPackage(pkgName) {
+	const metadata = resolvePackageMetadata(pkgName);
+	if (!metadata) {
+		return [];
+	}
+
+	const { pkgJson, pkgRoot } = metadata;
+	const exportKeys = getExportKeys(pkgJson.exports);
+
+	return exportKeys.flatMap((subpath) => {
+		const specifier = normalizeSubpath(pkgName, subpath);
+		try {
+			const target = moduleRequire.resolve(specifier);
+			const aliasKey =
+				subpath === '.' ? `${pkgName}$` : specifier.replace(/\\/g, '/');
+			return [[aliasKey, target]];
+		} catch (error) {
+			const aliasKey =
+				subpath === '.' ? `${pkgName}$` : specifier.replace(/\\/g, '/');
+			const fallbackTarget =
+				subpath === '.'
+					? path.join(pkgRoot, pkgJson.main ?? 'index.js')
+					: path.join(pkgRoot, subpath.replace(/^\.\//, ''));
+
+			if (fs.existsSync(fallbackTarget)) {
+				console.warn(
+					`docusaurus-dedupe-aliases: resolved ${specifier} via fallback path ${fallbackTarget} due to`,
+					error.message
+				);
+				return [[aliasKey, fallbackTarget]];
+			}
+
+			console.warn(
+				`docusaurus-dedupe-aliases: unable to resolve specifier ${specifier}`,
+				error
+			);
+			return [];
+		}
+	});
+}
+
+module.exports = function docusaurusDedupeAliases() {
+	const aliasEntries = PACKAGES_TO_DEDUPE.flatMap(buildAliasesForPackage);
+	const aliases = Object.fromEntries(aliasEntries);
+
+	return {
+		name: 'docusaurus-dedupe-aliases',
+		configureWebpack() {
+			return {
+				resolve: {
+					alias: aliases,
+				},
+			};
+		},
+	};
+};

packages/docs/site/plugins/docusaurus-dedupe-aliases.js

@@ -0,0 +1,74 @@
+const path = require('path');
+const typedocApiPlugin = require('docusaurus-plugin-typedoc-api');
+
+const typedocPackageRoot = path.dirname(
+	require.resolve('docusaurus-plugin-typedoc-api/package.json')
+);
+
+const componentMap = new Map(
+	['ApiPage', 'ApiIndex', 'ApiItem', 'ApiChangelog'].map((name) => [
+		path.join(typedocPackageRoot, `lib/components/${name}.js`),
+		path.join(__dirname, `../src/typedoc/${name}.tsx`),
+	])
+);
+
+function remapComponent(componentPath) {
+	if (!componentPath) {
+		return componentPath;
+	}
+
+	const normalized = path.normalize(componentPath);
+	for (const [original, replacement] of componentMap.entries()) {
+		if (normalized === original) {
+			return replacement;
+		}
+	}
+
+	return componentPath;
+}
+
+function remapRoutes(routes) {
+	if (!routes) {
+		return routes;
+	}
+
+	return routes.map(remapRoute);
+}
+
+function remapRoute(route) {
+	if (!route) {
+		return route;
+	}
+
+	return {
+		...route,
+		component: remapComponent(route.component),
+		routes: remapRoutes(route.routes),
+	};
+}
+
+module.exports = function typedocApiWrapper(context, options) {
+	const plugin = typedocApiPlugin(context, options);
+	const originalContentLoaded = plugin.contentLoaded?.bind(plugin);
+
+	return {
+		...plugin,
+		async contentLoaded(args) {
+			if (!originalContentLoaded) {
+				return;
+			}
+
+			const patchedActions = {
+				...args.actions,
+				addRoute(routeConfig) {
+					return args.actions.addRoute(remapRoute(routeConfig));
+				},
+			};
+
+			return originalContentLoaded({
+				...args,
+				actions: patchedActions,
+			});
+		},
+	};
+};

packages/docs/site/plugins/typedoc-api-wrapper.js

@@ -79,6 +79,16 @@
 			},
 			"dependsOn": ["build:json"]
 		},
+		"api-e2e": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"npm run build:docs",
+					"npx playwright test --config=packages/docs/site/playwright.config.ts --project=chromium"
+				],
+				"parallel": false
+			}
+		},
 		"lint": {
 			"executor": "@nx/linter:eslint",
 			"outputs": ["{options.outputFile}"],

packages/docs/site/project.json

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiChangelog from 'docusaurus-plugin-typedoc-api/lib/components/ApiChangelog.js';
+
+export default ApiChangelog as ComponentType<any>;

packages/docs/site/src/typedoc/ApiChangelog.tsx

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiIndex from 'docusaurus-plugin-typedoc-api/lib/components/ApiIndex.js';
+
+export default ApiIndex as ComponentType<any>;