Deploy the documentation

Maintainers only

This page describes publishing the documentation website from private source. Application developers only install and use the public package. They do not need repository access or publishing permissions.

Build and preview

pnpm

pnpm install --frozen-lockfile
pnpm docs:check
pnpm docs:build
pnpm docs:preview

npm

npm install
npm run docs:check
npm run docs:build
npm run docs:preview

Bun

bun install
bun run docs:check
bun run docs:build
bun run docs:preview

Yarn

yarn install
yarn docs:check
yarn docs:build
yarn docs:preview

Use Node 20 or newer for this project. For reproducible repository builds use pnpm with its committed lockfile. Output is docs/.vitepress/dist.

Vercel

Import the GitHub repository. The included vercel.json selects VitePress, runs documentation checks and the build, and publishes docs/.vitepress/dist. English and Spanish pages are both static output. No server function is required.

Netlify and Cloudflare Pages

Set build command to pnpm docs:check && pnpm docs:build and output directory to docs/.vitepress/dist. Point the site at the repository root and use Node 20+. Netlify also has a checked-in netlify.toml.

GitHub Pages and subpaths

DOCS_BASE=/serial-node-jsd/ pnpm docs:build

Upload the contents of docs/.vitepress/dist as the Pages artifact. Use the same base for preview. Root deployments need no DOCS_BASE override.

The site uses explicit .html page URLs so static hosting does not depend on clean-URL rewrites. Directory homepages remain / and /es/.

Translation maintenance

English is canonical at docs/; Spanish mirrors every page under docs/es/. Navigation and search labels are localized. Keep the relative path identical when adding a page so the locale selector preserves the current topic. Run pnpm docs:generate after changing event payloads or method signatures.

Before publishing, preview the production output, switch languages on an API page, follow sidebar and previous/next links, test search, and reload a deep URL.