Automate npm Release
Use this skill to set up npm release automation. First identify the repository shape, then load the matching reference:
- Single publishable package: see SINGLE_PACKAGE.md.
- Workspace monorepo with independently published packages: see MONOREPO.md.
Shared rules
- npm requires the first publish to be done manually for each public package:
npm publish --access public
- Prefer npm trusted publishing/OIDC when the project asks for it. Configure the package on npmjs.com after the first manual publish, then use
id-token: writein GitHub Actions. Ensurepackage.jsonhasrepository.urlexactly matching the GitHub repo URL (case-sensitive) — required for provenance validation. - If using token-based publishing, configure
actions/setup-nodewithregistry-url: https://registry.npmjs.orgsoNODE_AUTH_TOKENcan authenticatenpm publish. - In pnpm workspaces, publish via
pnpm packfollowed bynpm publish <tarball> --access public. This lets pnpm rewriteworkspace:*dependencies while npm handles trusted publishing/OIDC. Use changelogithub only for GitHub release notes/releases. - Always run checks, tests, and package builds before publishing.
- Keep the private workspace root unpublished; publish from the actual package directory.
Quick choice
Use single-package release automation when one package.json owns the npm artifact and one v* tag maps to one package.
Use monorepo release automation when multiple workspace packages publish independently. In that flow, tags must encode the package, such as cli-v0.1.0, and GitHub release-note generation must use explicit previous same-package tag ranges.
Workflow examples
- EXAMPLE_WORKFLOW.yml — single-package token/provenance workflow.
- MONOREPO_WORKFLOW.yml — package-scoped monorepo workflow using trusted publishing and changelogithub.