From b8b1709db5f7fe8ec35cb5484f075a9972baf9f4 Mon Sep 17 00:00:00 2001 From: Darius Cepulis Date: Mon, 22 Jun 2026 09:43:49 -0700 Subject: [PATCH] fix(site): pre-bundle react-dom so dev islands hydrate (#1711) Co-authored-by: Claude --- site/CLAUDE.md | 21 ++++++++++++++++++--- site/astro.config.mjs | 5 +++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/site/CLAUDE.md b/site/CLAUDE.md index 71ad07ed..e642f1b1 100644 --- a/site/CLAUDE.md +++ b/site/CLAUDE.md @@ -581,17 +581,32 @@ vi.mock('@/types/docs', async () => { ## Technology Stack -- **[Astro 5.14.4](https://astro.build)**: Static site generation with island architecture +- **[Astro 6.3.1](https://astro.build)**: Static site generation with island architecture +- **[Vite 7](https://vite.dev)**: Underlying dev server and bundler (Astro 6 adopts Vite's Environment API — see "Dependency Optimization" gotcha below) - **[React 19](https://react.dev)**: Client-side interactive components (`client:load`) - **[React Compiler](https://react.dev/learn/react-compiler)**: Enabled via `babel-plugin-react-compiler` targeting React 19 - **[Tailwind v4](https://tailwindcss.com)**: CSS utility classes via `@tailwindcss/vite` - **[Nanostores 1.0.1](https://github.com/nanostores/nanostores)**: Cross-island state - **[Base UI 1.2.0](https://base-ui.com)**: Headless accessible components - **[Algolia DocSearch v4](https://docsearch.algolia.com)**: Search via Algolia-hosted indexes (docs + blog) -- **[Shiki 3.13.0](https://shiki.style)**: Syntax highlighting -- **[Vitest 3.2.4](https://vitest.dev)**: Testing framework +- **[Shiki 4](https://shiki.style)**: Syntax highlighting +- **[Vitest 4](https://vitest.dev)**: Testing framework - **[clsx](https://github.com/lukeed/clsx)**: Class name concatenation utility +### Dependency Optimization (Vite) — gotcha + +`astro.config.mjs` sets `vite.optimizeDeps` (e.g. `exclude` for the workspace +`@videojs/*` packages and the native `@resvg/resvg-js` binding). Since the +Astro 6 / Vite 7 upgrade, this root-level `optimizeDeps` **shadows** the +per-environment `optimizeDeps.include` that renderer integrations +(`@astrojs/react`) inject via Vite's Environment API — so React's CJS deps stop +being pre-bundled in **dev only**. The symptom is every React island failing to +hydrate with `SyntaxError: Importing binding name 'createRoot' is not found` +(prod is unaffected — Rollup bundles everything). Fix: re-declare the needed +entries in the site's own `optimizeDeps.include` (currently `react-dom` and +`react-dom/client`). If you add another renderer integration, include its +client deps here too. + ## API Reference Generation > **Source of truth:** [`scripts/api-docs-builder/src/tests/e2e.test.ts`](scripts/api-docs-builder/src/tests/e2e.test.ts) diff --git a/site/astro.config.mjs b/site/astro.config.mjs index f076c02d..edf98e57 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -172,6 +172,11 @@ export default defineConfig({ // @resvg/resvg-js loads a native .node binding for the server-only OG // image route, so Vite's dev optimizer must leave it external. exclude: ['@videojs/react', '@videojs/html', '@resvg/resvg-js'], + // react-dom (CJS) must be pre-bundled so its named exports (createRoot, + // hydrateRoot) are exposed as ESM bindings to the @astrojs/react client + // renderer. Excluding @videojs/react above shadows the include list the + // React integration injects, so re-declare them here. + include: ['react-dom', 'react-dom/client'], }, resolve: { dedupe: ['react', 'react-dom'],