feat: partial hydration

[avivkeller]

Uses islands from 11ty in order to give us partial hydration

[cursor]

PR Summary

Medium Risk
Large change to how docs pages load and hydrate JS/CSS; regressions could affect interactivity, styling on first paint, or SSR/client markup mismatches, though scope is confined to the web generator.

Overview
Replaces full-page client hydration with island-based partial hydration using @11ty/is-land. Interactive UI (banner, sidebar, search, theme toggle, code copy/tabs) is wrapped in withIsland, which on the server emits <is-land> markup, serialized props, and <island-slot> children so static HTML stays in the document and is re-adopted on hydrate instead of being rebuilt from JS.

The client bundle model changes: every page shares one entry that imports global CSS, runs registerIslands, and dynamically imports components by name; SSR programs only import components actually referenced on that page. Vite client builds disable cssCodeSplit so styles are not tied to late-loading island chunks.

Layout always renders the banner (no client-only guard). Theme toggle moves into its own island component. CodeTabs gets a local island wrapper (constants point at it). Type annotations in the web pipeline use dual Shiki themes for light/dark. Lockfile bumps @node-core/ui-components, @node-core/rehype-shiki, Radix, React 19.2.8, and related deps.

^{Reviewed by Cursor Bugbot for commit 1ef01c2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Aug 1, 2026 5:12pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nodejs-doc-kit	Ignored		Aug 1, 2026 5:12pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.12%. Comparing base (96e1c26) to head (1ef01c2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #951   +/-   ##
=======================================
  Coverage   89.11%   89.12%           
=======================================
  Files         196      196           
  Lines       18075    18083    +8     
  Branches     1664     1667    +3     
=======================================
+ Hits        16108    16116    +8     
  Misses       1960     1960           
  Partials        7        7           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 797e8af. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[AugustinMauroy]

idk why but when I take a page an scroll I have some lag spike in safari 26.5.2

[avivkeller]

idk why but when I take a page an scroll I have some lag spike in safari 26.5.2

I can't reproduce, probably a browser issue. If anything, this should lower spikes since it's less JS

[bmuenzenmeyer]

I am still learning this architecture, but don't want to be a blocker.

[ovflowd]

I see some light themed items on dark mode?

Whereas on beta.docs.nodejs.org correctly colored?

[avivkeller]

That's probably a bug of the ui bump

[ovflowd]

That's probably a bug of the ui bump

I believe so

[avivkeller]

Actually, it might be because in this repo we don't account for a light/dark mode in Shiki (we use .[0], I'll fix it

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated no new comments.

Suppressed comments (3)

packages/core/src/generators/web/ui/index.css:20

• Selector targets data-component, but islands are marked with data-island-name (see withIsland.jsx). As written, the SideBar-specific rule will never match and the flex layout tweaks won’t apply.

/* TODO(@avivkeller): make this component's CSS more agnostic */
is-land[data-component='SideBar'] {
  display: flex;

packages/core/src/generators/web/ui/islands/runtime.mjs:41

• JSON.parse(script.textContent) can throw (e.g. if the inline JSON is malformed or truncated), which would reject the addInitType callback and leave the island stuck before it’s marked ready. Parse errors should be caught and reported like the hydration errors below.

  const script = [...island.children].find(child =>
    child.matches('script[data-island-props]')
  );

  const props = script ? JSON.parse(script.textContent) : {};

packages/core/src/utils/type-annotations/hast.mjs:107

• The inline <code> produced from Shiki drops preElement.properties.style. Shiki uses inline styles/CSS variables for theme colors, so removing this can break highlighting (especially with dual themes). Preserve the style on the reshaped <code> like the legacy highlighter does.

    tagName: 'code',
    properties: {
      class: `${preElement.properties.class} type`,
    },
    children: codeElement.children,

[avivkeller]

@ovflowd Fixed!

[avivkeller]

Can I get approvals so I can land this :-)

[ovflowd]

SGTM, although we should be conscious about the footprint the ever-increasing dependencies are causing to doc-kit... I wish for doc-kit to be relatively small to install and not bloated.