Local Development

Install

Use Node.js 24 (the .nvmrc and CI baseline) and the exact pnpm version in the root packageManager field. With nvm, run nvm use; other version managers can select Node 24 directly. On Windows, use PowerShell or your normal terminal. The pnpm commands below work across platforms. If pnpm is not installed, install the version declared by this checkout; do not regenerate the lockfile with a different package manager.

node --version
pnpm --version
pnpm install --frozen-lockfile

Common Commands

Release Gate

Ordinary contributions need the checks affected by the change, rather than a full release rehearsal. See collaboration for the package map and review process, and translations for language changes. Public contributors do not need registry, deployment, private-repository, or customer-file access.

For an initial focused source change:

pnpm --filter @file-viewer/core build
pnpm exec vitest run test/core-options.spec.ts
pnpm verify:github-governance

Use the target package's own package.json for its build and type-check commands. A missing workspace declaration often means its dependency has not been built yet; build that dependency instead of adding a type suppression. In pnpm filters, <package>... includes dependencies. The contribution guide defines fixture and screenshot requirements.

Before publishing packages or deploying production, run the focused checks for the area you changed. Renderer and asset changes should at least pass:

pnpm build-only
pnpm docs:build
pnpm verify:format-support
pnpm verify:renderer-assets
pnpm verify:smoke-matrix
pnpm verify:npm-install-smoke

Use pnpm verify:migration-gates for a broader migration gate.

Batch Release Safety

The private maintainer checkout builds and freezes the package artifacts once. Local packing uses four workers by default (FILE_VIEWER_PACK_CONCURRENCY); registry download and comparison use four (FILE_VIEWER_REGISTRY_CONCURRENCY). Both accept 1–8 workers. Reusing an already-built artifact is only valid when its source and dependency inputs are unchanged; it does not replace the frozen-release checks.

The GitHub npm workflow publishes the immutable Release tarballs with trusted publishing. It checks all package identities and integrity hashes before the first upload, then publishes in dependency layers, with up to three uploads and six registry checks at a time. A layer must become visible with matching integrity before dependent packages can start. Failures stop new work and wait for active operations to finish; rerunning the same Release skips only versions whose bytes already match. An authorization failure or registry delay is not a reason to allocate another version.

Compatibility aliases need their own version bump when their exact dependency changes. In particular, reusing an old msdoc-viewer version would keep those users on its old DOC renderer even after the other packages are updated. The version-freeze check rejects that plan. Registry verification, cold installs, production Demo checks and the final release postcheck are still required after publishing.