feat(html): client-side navigation with the Navigation API by ovflowd · Pull Request #1117 · nodejs/doc-kit

ovflowd · 2026-09-30T08:50:15Z

Description

This PR adds client-side navigation: clicking a link no longer loads a new page from scratch. Instead, the browser fetches just the HTML for the next page, swaps the <body> in, and keeps running — scripts, stylesheets, fonts, and in-memory data all stay loaded.

Without this, every click on a doc-kit site is expensive. With max-age=0, must-revalidate, the browser has to revalidate every asset on each page load: on doc-kit.nodejs.org that's a 308 redirect (.html → clean URL) plus 27 round-trips before anything renders.

How the intercept works. Modern browsers fire a navigate event before leaving a page. The router calls event.intercept() to handle the navigation itself — it fetches the target page's HTML, swaps the <body> and page-level <head> tags, and calls event.scroll() when done. The browser still manages history entries, back/forward, scroll restoration, focus, and the loading indicator. The router just handles the DOM swap.

What changed

Router (`ui/router.mjs`)

Intercepts same-site page navigations via the Navigation API (Baseline since January 2026)
Prefetches pages on hover (80 ms delay) and on pointer-down, so most clicks never wait on the network
Falls back to a full browser load for: links to other sites or builds, files that aren't pages (.json, .md), browsers without the Navigation API, and pages from a different deploy (mismatched asset hashes)
The router's scope and asset list are embedded by the generator as a <script type="application/json" data-router> tag — no DOM queries needed at startup

Island lifecycle

Islands are unmounted before the body swap so their effects clean up (the search box's ⌘K listener used to pile up across navigations)
Already-loaded components hydrate synchronously before the next paint — no flash of unhydrated content on navigated pages
The banner's slide-in animation only runs on the first page load; <html data-navigated> suppresses it on subsequent ones

Shared data

The Orama index (9.4 MB on the Node.js docs) is fetched and loaded once per visit, reused across all pages
The remote config is fetched once per visit and shared across all islands (previously fetched once per island — twice per page)

Speculation rules

Scope changed from "prefetch all same-origin links" to "prefetch same-origin links that leave the site". Speculative prefetch only benefits full-document navigations; for pages the router handles, it would just double-download them.

Asset caching

Fonts are now content-hashed like every other asset (preload URLs come from Vite's manifest). All of assets/ can be served immutable. vercel.json is updated; docs/publishing.md documents the pattern for other hosts.

Validation

Built the Node.js v26.10.0 docs (section-pages + orama-db) and clicked around:

	Before	After
Requests per click	1 redirect + 27 asset revalidations	1 HTML fetch, or none if the link was hovered
Orama index	re-fetched on every page	once per visit

Back/forward restores scroll position; #fragment links land on the right element
The sidebar keeps its scroll position and active item across page depths (fs.html → fs/promises-api.html → ../path.html)
Added e2e/client-side-navigation.spec.js: no asset refetches, scroll restoration, hover prefetch, shared remote config, and non-page links falling through to the browser
Unit tests for the router's URL rules and shouldIntercept, speculation rules scope, and hashed font preloads

cleanUrls on Vercel still turns every .html link into a 308 (~70 ms per page fetch) — worth a follow-up.

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format:check & node --run lint.
I've covered new added functionality with unit tests if necessary.

Refs: #459

vercel · 2026-09-30T08:50:22Z

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

Project	Deployment	Actions	Updated
api-docs-tooling	Ready	Preview	Sep 30, 2026 2:49pm UTC

cloudflare-workers-and-pages · 2026-09-30T08:50:24Z

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗	`6acb976`	2026-09-30T15:42:37.571Z	View logs ↗
Build: Failed ❌ View logs ↗	`65e547d`	2026-09-30T14:47:35.426Z	View logs ↗
Build: Failed ❌ View logs ↗	`faf7afb`	2026-09-30T14:30:58.209Z	View logs ↗
Build: Failed ❌ View logs ↗	`da720ce`	2026-09-30T14:11:10.862Z	View logs ↗
Build: Failed ❌ View logs ↗	`790f66b`	2026-09-30T12:19:17.012Z	View logs ↗
Build: Failed ❌ View logs ↗	`a411d86`	2026-09-30T10:07:48.352Z	View logs ↗
Build: Failed ❌ View logs ↗	`e7ed0e0`	2026-09-30T09:55:48.642Z	View logs ↗
Build: Failed ❌ View logs ↗	`122ac33`	2026-09-30T08:50:44.194Z	View logs ↗

codecov · 2026-09-30T08:51:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.64%. Comparing base (6c484cb) to head (6acb976).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1117      +/-   ##
==========================================
+ Coverage   91.38%   92.64%   +1.25%     
==========================================
  Files         249      244       -5     
  Lines       23253    23121     -132     
  Branches     2244     2260      +16     
==========================================
+ Hits        21250    21420     +170     
+ Misses       1994     1692     -302     
  Partials        9        9

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

github-actions · 2026-09-30T08:52:30Z