跳至主要内容

NProgress Page Transition Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a global top progress bar when navigating between Docusaurus docs pages.

Architecture: Register a Docusaurus client module that hooks into route-update lifecycle events, starts nprogress for real client-side navigations, and finishes it when the next route chunk has loaded. Keep visual styling isolated in a dedicated CSS file and wire the module through site config.

Tech Stack: Docusaurus 3, React 19, TypeScript, nprogress

Task 1: Wire Global Route Progress​

Files:

  • Modify: docusaurus.config.ts

  • Create: src/client-modules/nprogress.ts

  • Create: src/css/nprogress.css

  • Step 1: Register the client module

Add clientModules in docusaurus.config.ts pointing at ./src/client-modules/nprogress.ts.

  • Step 2: Add the route lifecycle module

Create src/client-modules/nprogress.ts that configures nprogress, ignores the first page load, starts progress on route updates, and returns a cleanup callback that finishes the bar after preload completes.

  • Step 3: Add the progress bar styles

Create src/css/nprogress.css with a thin fixed top bar, primary-color fill, subtle glow, and no spinner.

  • Step 4: Verify the integration

Run: pnpm typecheck Expected: PASS

Run: pnpm build Expected: PASS