npm-patch-release

name

npm-patch-release

description

Update an npm package patch version, changelog, and lockfile; run relevant tests/checks; commit the release changes; and give the user the exact npmjs publish command, preferring repo publish scripts such as scripts/publish-npmjs.sh, without publishing. Use when asked to "update patch version, changelog; commit; give me a command to publish this to npmjs" or similar npm package release-prep tasks.

NPM Patch Release

Perform release prep for an npm package. Do not publish or push unless explicitly asked.

Workflow

1. Inspect state and identify the target package.

   • Run git status --short.
   • Find relevant package.json and CHANGELOG.md files.
   • If multiple packages could match and the user did not specify one, ask which package to release.

2. Review existing changes.

   • Run git diff -- <target files> and include only intended package files.
   • If unrelated or ambiguous changes exist, ask before staging them.

3. Bump the patch version without creating a git tag.

   • For npm workspaces, prefer:

     npm version patch --workspace <workspace-name-or-path> --no-git-tag-version
     

   • For a standalone package, run from the package directory:

     npm version patch --no-git-tag-version
     

   • Keep lockfiles updated when the command modifies them.

4. Update the package changelog.

   • Add a new top entry under # Changelog.
   • Use the new version and current date in YYYY-MM-DD format.
   • Summarize user-visible changes concisely.

5. Validate.

   • Run existing tests/checks relevant to the package.
   • If this repo has scripts/publish-npmjs.sh, run the publish script in dry-run mode from the repo root instead of raw npm pack / npm publish dry-runs:

     scripts/publish-npmjs.sh <package-directory> --dry-run
     

     For all packages:

     scripts/publish-npmjs.sh --all --dry-run
     

   • If no repo publish script exists, run a packaging dry-run when practical:

     npm pack --workspace <workspace-name-or-path> --dry-run
     

     or from a standalone package directory:

     npm pack --dry-run
     

6. Commit.

   • Read and follow the commit skill if available before committing.
   • Stage only release-related files: package manifest, lockfile, changelog, docs/code changes being released.
   • Use a concise Conventional Commits subject, usually:

     git commit -m "chore(<package-scope>): release <version>"
     

   • Never use --no-verify.

7. Report.

   • Include the commit hash, version, validation commands run, and publish command.
   • Give a command only; do not publish.

Publish Command

If this repo has scripts/publish-npmjs.sh, give the user that command from the repo root and do not publish yourself:

scripts/publish-npmjs.sh <package-directory>

For all packages:

scripts/publish-npmjs.sh --all

Add --only-unpublished when releasing multiple packages or when the user may rerun the command safely:

scripts/publish-npmjs.sh --all --only-unpublished

Only fall back to raw npm commands when no repo publish script exists.

For npm workspaces:

npm publish --workspace <workspace-name-or-path> --access public

For standalone packages, from the package directory:

npm publish --access public