Skip to content
Public template

About

Repository template for pnpm TypeScript monorepos that publish to npm

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Project Template: pnpm

A repository template for TypeScript monorepos managed with a pnpm workspace that publish packages to npm.

It layers a pnpm workspace, shared lint and format rules, CI, and an npm release flow on top of the stack-agnostic PerfectPan/project-template, and keeps that template's contribution workflow (Spec + Plan), review checks, Git hooks and documentation standards.

Stack

Concern Choice
Monorepo pnpm 12.8.1 workspace, pinned in the root package.json packageManager field; members in pnpm-workspace.yaml
Runtime Node.js ^26.13.1 for development and CI; .node-version selects major 26. engines and devEngines.runtime enforce the security floor (>=26.13.1 <27), and CI resolves the latest matching release
Language TypeScript 7.0.2, tsconfig extends @perfectpan/lint-config/tsconfig/node.json
Toolchain Vite+ (vp) 1.1.0 for build (vp pack), lint (vp lint), format (vp fmt) and tests (vp test); shared settings from @perfectpan/lint-config v0.7.1; type check stays tsc
Tests Vitest 5 bundled in Vite+; test files import from vite-plus/test
Shared versions External dependencies used by workspace packages live in the pnpm-workspace.yaml catalog; catalogMode: strict rejects pnpm add of a cataloged package at an off-catalog version
Releases Changesets (pnpm changeset) with changesets/action: automatic draft version PR on main, npm Trusted Publishing with provenance, one tag and GitHub Release per published package

Quick Start

  1. Create the repository from this template (GitHub Use this template, or gh repo create OWNER/REPO --public --template PerfectPan/project-template-pnpm --clone).

  2. Rename the placeholders.

    • Package scope and name: @scope/example in packages/example/package.json (name, repository.url and the directory) and its README. Rename or replace packages/example itself as needed. The example package ships "private": true with no publishConfig, so the template's own Release workflow has nothing to publish: once the renamed package is ready to release, remove "private": true, add "publishConfig": { "access": "public" } and record its first change with pnpm changeset (see docs/development/release.md).
    • Repository URL: PerfectPan/project-template-pnpm in every published package.json repository.url. npm provenance requires it to match the publishing repository.
    • Root package.json name and this README. Pick the license by project type: libraries and tools keep the MIT LICENSE (update the holder); applications switch to GPL-3.0-only (see CONTRIBUTING.md License).
  3. Install and check.

    gh extension install PerfectPan/gh-repo-checks
    ./scripts/install-git-hooks.sh
    pnpm install
    pnpm run check
  4. Protect the default branch with an admin-authorized gh session:

    gh repo-checks protect --repo OWNER/REPO --approvals 0 --check check --apply

    --check check requires the CI job named check next to the review checks. --approvals 0 suits a single maintainer, who cannot approve their own pull requests; drop it to require one approving review.

    Also allow GitHub Actions to create pull requests (Settings → Actions → General) so Version Packages can open the release PR.

  5. Set up npm Trusted Publishing for every package before the first release, following docs/development/release.md.

Layout

pnpm-workspace.yaml           workspace members, the shared dependency catalog, pnpm and release settings
pnpm-lock.yaml                the one lockfile for the whole workspace
.changeset/                   pending change records, consumed by the Release workflow
packages/example/             example public library: src, vp pack build to dist, vite-plus/test suite
scripts/                      repo-scripts project and the template's shell checks
.github/workflows/            ci.yml, review.yml, publish-npm.yml
docs/development/release.md   release runbook

The root package.json is itself a private workspace project — pnpm counts it among the workspace projects, it publishes nothing, and its scripts call pnpm -r, so pnpm run check works from the repository root.

Commands

Command What it runs
pnpm run check format:check, build, lint, typecheck, test (repository checks run in the Review workflow and the pre-commit hook)
pnpm run build / lint / typecheck / test / format / format:check pnpm -r run <task>: the task in every workspace package that defines it
pnpm --filter @scope/example run test one package's task; add ... after the name to include its workspace dependencies
pnpm changeset record a change for the affected published packages
pnpm run version-packages changeset version: consume change records, bump versions, write changelogs

CI and Releases

  • ci.yml runs pnpm run check when a Ready PR is opened, updated with new commits, reopened, or marked Ready, and on pushes to main. Draft PR events skip the full job; a skipped check is not evidence that tests ran. pnpm/setup installs pnpm and Node from the pinned versions, installs with --frozen-lockfile, and caches the pnpm store keyed on the lockfile. See CI Execution Policy.
  • review.yml (from the upstream template) keeps lightweight repository hygiene, title and description checks active on Draft PRs and metadata edits, without running the full test suite.
  • publish-npm.yml calls the shared npm release workflow of PerfectPan/gh-repo-checks on every push to main: with pending change records it opens or updates the draft PR chore(release): version packages from changeset-release/main; when a merged version PR has consumed them it publishes through npm Trusted Publishing and tags and releases each package. See docs/development/release.md.
  • Dependabot updates npm dependencies and GitHub Actions weekly with chore(deps) titles. Dependabot officially supports pnpm 7–10; on pnpm 12 its support is limited (dependabot-core#16397), so a PR may edit package.json or the catalog without regenerating pnpm-lock.yaml — run pnpm install and commit the lockfile on the branch before merging. See docs/development/release.md.

Workflows reference actions by their latest major version tag, such as actions/checkout@v7, not by commit SHA. See docs/development/release.md for the release procedure and recovery steps.

License

MIT. See LICENSE. Projects created from this template choose their own license by project type.

Template Maintenance

Generic files come from PerfectPan/project-template: the policy sections of AGENTS.md and CONTRIBUTING.md, SECURITY.md, docs/README.md, docs/specs/, docs/plans/, the PR/MR and issue templates, .githooks/pre-commit, .github/workflows/review.yml, and the shell scripts under scripts/. Sync those from upstream instead of editing them here, then keep the pnpm-specific additions:

  • the filled command sections in AGENTS.md, CONTRIBUTING.md and the PR/MR templates;
  • .githooks/pre-push, and everything pnpm, npm or TypeScript specific.

Keep this template free of project-specific business logic; packages/example stays a minimal example.

About

Repository template for pnpm TypeScript monorepos that publish to npm

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages