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.
| 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 |
-
Create the repository from this template (GitHub Use this template, or
gh repo create OWNER/REPO --public --template PerfectPan/project-template-pnpm --clone). -
Rename the placeholders.
- Package scope and name:
@scope/exampleinpackages/example/package.json(name,repository.urland the directory) and its README. Rename or replacepackages/exampleitself as needed. The example package ships"private": truewith nopublishConfig, 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 withpnpm changeset(see docs/development/release.md). - Repository URL:
PerfectPan/project-template-pnpmin every publishedpackage.jsonrepository.url. npm provenance requires it to match the publishing repository. - Root
package.jsonnameand this README. Pick the license by project type: libraries and tools keep the MITLICENSE(update the holder); applications switch to GPL-3.0-only (seeCONTRIBUTING.mdLicense).
- Package scope and name:
-
Install and check.
gh extension install PerfectPan/gh-repo-checks ./scripts/install-git-hooks.sh pnpm install pnpm run check
-
Protect the default branch with an admin-authorized
ghsession:gh repo-checks protect --repo OWNER/REPO --approvals 0 --check check --apply
--check checkrequires the CI job namedchecknext to the review checks.--approvals 0suits 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.
-
Set up npm Trusted Publishing for every package before the first release, following docs/development/release.md.
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.
| 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.ymlrunspnpm run checkwhen a Ready PR is opened, updated with new commits, reopened, or marked Ready, and on pushes tomain. Draft PR events skip the full job; a skipped check is not evidence that tests ran.pnpm/setupinstalls 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.ymlcalls the shared npm release workflow of PerfectPan/gh-repo-checks on every push tomain: with pending change records it opens or updates the draft PRchore(release): version packagesfromchangeset-release/main; when a merged version PR has consumed them it publishes through npm Trusted Publishing and tags and releases each package. Seedocs/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 editpackage.jsonor the catalog without regeneratingpnpm-lock.yaml— runpnpm installand 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.
MIT. See LICENSE. Projects created from this template choose their own license by project type.
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.mdand 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.