Migrate docs from npm to pnpm, fix all Docusaurus deprecation warnings #70

New Issue

kert · 2026-03-21T19:52:00Z

kert commented

2026-03-21 19:52:00 +00:00

Problem

The docs site uses bare npm with no lockfile discipline, and the Docusaurus build emits deprecation warnings that will become errors in v4.

npm issues:

package-lock.json is bloated and not deterministic across environments
No workspace-aware package management
npm install in Dockerfile is slow (no cache reuse)
No strict dependency resolution

Deprecation warnings (from build output):

siteConfig.onBrokenMarkdownLinks — must move to siteConfig.markdown.hooks.onBrokenMarkdownLinks
Possibly others — need full audit of build output

Plan

1. Migrate to pnpm

Delete package-lock.json
Add pnpm-lock.yaml (generated by pnpm install)
Add packageManager field to package.json: "packageManager": "pnpm@10.x"
Update docs/Dockerfile:
- Install pnpm: RUN corepack enable && corepack prepare pnpm@latest --activate
- Replace npm install → pnpm install --frozen-lockfile
- Replace npm run build → pnpm build
Update any scripts or CI that reference npm for docs

2. Fix all deprecation warnings

Audit: run pnpm build and capture ALL warnings
Fix each one per Docusaurus v4 migration guide
Known: onBrokenMarkdownLinks config key needs migration

3. Add .npmrc / .pnpmrc for project config

auto-install-peers=true
strict-peer-dependencies=false (Docusaurus has peer dep issues)

Files

docs/package.json
docs/package-lock.json (delete)
docs/pnpm-lock.yaml (new)
docs/Dockerfile
docs/docusaurus.config.js
docs/.npmrc (new, optional)

## Problem The docs site uses bare `npm` with no lockfile discipline, and the Docusaurus build emits deprecation warnings that will become errors in v4. ### npm issues: - `package-lock.json` is bloated and not deterministic across environments - No workspace-aware package management - `npm install` in Dockerfile is slow (no cache reuse) - No strict dependency resolution ### Deprecation warnings (from build output): - `siteConfig.onBrokenMarkdownLinks` — must move to `siteConfig.markdown.hooks.onBrokenMarkdownLinks` - Possibly others — need full audit of build output ## Plan ### 1. Migrate to pnpm - Delete `package-lock.json` - Add `pnpm-lock.yaml` (generated by `pnpm install`) - Add `packageManager` field to `package.json`: `"packageManager": "pnpm@10.x"` - Update `docs/Dockerfile`: - Install pnpm: `RUN corepack enable && corepack prepare pnpm@latest --activate` - Replace `npm install` → `pnpm install --frozen-lockfile` - Replace `npm run build` → `pnpm build` - Update any scripts or CI that reference `npm` for docs ### 2. Fix all deprecation warnings - Audit: run `pnpm build` and capture ALL warnings - Fix each one per Docusaurus v4 migration guide - Known: `onBrokenMarkdownLinks` config key needs migration ### 3. Add .npmrc / .pnpmrc for project config - `auto-install-peers=true` - `strict-peer-dependencies=false` (Docusaurus has peer dep issues) ## Files - `docs/package.json` - `docs/package-lock.json` (delete) - `docs/pnpm-lock.yaml` (new) - `docs/Dockerfile` - `docs/docusaurus.config.js` - `docs/.npmrc` (new, optional)

kert added this to the P13: Docs Search — local search, library data, broken links, tests milestone 2026-03-21 19:52:00 +00:00

kert added the config docs labels 2026-03-21 19:52:00 +00:00

kert referenced this issue from a commit

2026-03-21 19:56:31 +00:00

migrate docs from npm to pnpm, fix Docusaurus deprecation warnings

kert closed this issue

2026-03-21 19:56:31 +00:00

Sign in to join this conversation.