Development Workflow
Development commands, build tools, and component development patterns for zudo-doc.
Development Commands
These commands start the local development servers.
| Command | What it does |
|---|---|
pnpm dev | Runs the zfb dev server (port 4321) and doc-history-server (port 4322) concurrently |
pnpm dev:zfb | zfb dev server only (port 4321) |
pnpm dev:history | Doc history API server only (port 4322) |
pnpm dev:zudo-doc | tsup --watch for the @takazudo/zudo-doc package |
pnpm dev:stable | Alternative build-then-serve mode (avoids HMR crashes on content file add/remove) |
pnpm dev:network | zfb dev server with --host 0.0.0.0 for LAN access |
Tip
Use pnpm dev:stable when you're adding or removing content files frequently. Standard pnpm dev can crash on file system changes due to Vite HMR.
Build & Quality Commands
| Command | What it does |
|---|---|
pnpm build | Static HTML export to dist/ |
pnpm check | TypeScript type checking |
pnpm b4push | Pre-push validation: 19-step pipeline (format check → ... → build → link check → HTML validation → preview smoke); E2E is parked |
pnpm format | Format MDX files |
pnpm test:unit | Run unit tests (Vitest) |
pnpm test:e2e | Run E2E tests (Playwright) |
Note
Run pnpm b4push before pushing to verify the full site builds and all links resolve. It runs 19 steps (format check through preview smoke); E2E tests are intentionally parked and not part of this pipeline.
The canonical, authoritative b4push step list lives in the header comment of scripts/ — treat that script as the single source of truth, and consult it rather than any inline summary if the steps appear to disagree.
Component Development
zudo-doc is a Preact-only project running on zfb. All components are .tsx files. The distinction is whether a component runs only on the server, or also hydrates on the client.
Server-rendered Preact components
By default, every .tsx component renders to HTML at build time and ships zero client-side JavaScript. This is the right choice for:
Layout wrappers
Static UI elements (headers, footers, sidebars without interactivity)
Anything that doesn't require runtime state or DOM events
Client-hydrated islands
When a component needs interactivity — local state, event handlers, animations — it registers itself with zfb's island runtime through its own useEffect / event-binding code. Server-render output is reused; only the interactive part hydrates.
Current islands in the project: toc.tsx, mobile-toc.tsx, sidebar-toggle.tsx, sidebar-tree.tsx, theme-toggle.tsx, doc-history.tsx, zdtp panel (Design Token Panel — self-mounted via configurePanel() from the @takazudo/zdtp package, not registered in the island registry), ai-chat-modal.
Use client-hydrated islands for:
Scroll spy (TOC highlighting)
Toggle/drawer components
Live editing panels
Content Typography Components
These live in src/ and are Preact function components that render purely on the server — no client hydration. They override standard HTML elements in MDX via the _mdx-components.ts mapping consumed by the doc page route.
Current overrides: headings (h2–h4), paragraph, link, strong, blockquote, lists (ul/ol), table.
Use content typography components when you need to apply project design tokens to standard MDX prose elements.
Content Development Cycle
Follow these steps when adding new documentation pages:
Create a
.mdxfile undersrc/withcontent/ docs/ titleandsidebar_positionin the frontmatter.Write content starting with
## h2headings. Do not add# h1— the frontmattertitlerenders as the page h1.Create a matching file under
src/with translated prose.content/ docs- ja/ Keep all code blocks identical between EN and JA — only translate the surrounding prose.
Run
pnpm formatto format MDX files.Run
pnpm buildto verify the site builds correctly.
Tip
Always set sidebar_position in frontmatter. Without it, pages sort alphabetically, which is rarely the intended order.
See the Frontmatter reference for all available frontmatter fields.