Jak używać
- Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
- W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
- Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/alexbruno/dev-skills --skill npm-version-managementPrzed rozpoczęciem
- Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
- Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.
NPM Version Management
Define strict policies and workflows for managing and updating NPM package versions in Node.js and JavaScript/TypeScript projects.
The Cardinal Rule: Never Manually Edit package.json Version
[!CAUTION] NEVER manually edit the `"version"` field in `package.json` using file editing tools, text editors, or search-and-replace scripts. All version bumps MUST be executed strictly through the official npm version command.Why Git Tag Synchronization Matters
In a Git repository, the npm version command performs three critical atomic operations:
- Updates Manifests: Safely bumps the
"version"field inpackage.jsonand updatespackage-lock.json(preserving formatting and indentation). - Creates a Git Commit: Stages the manifest changes and generates a dedicated release commit with a standardized message (default:
v<version>). - Creates a Git Tag: Creates an annotated Git tag matching the new version (e.g.,
v1.2.3).
Consequences of Manual Editing
Manual editing bypasses this integrated workflow and causes severe issues:
- Version Drift: The version declared in
package.jsondiverges from Git tags. - CI/CD Pipeline Breakage: Modern release pipelines, automated changelogs, container registries, and package registries (NPM, GitHub Packages) rely on Git tags matching the manifest version.
- Broken Release Tracking: Git history loses the explicit release boundary, complicating rollbacks,
git bisect, and semantic comparisons.
Pre-Bump Checklist
Before running npm version, ensure the following prerequisites are met:
- Clean Working Tree:
- The Git working directory MUST be clean:
git status --porcelain- If uncommitted changes exist, commit or stash them first. Never bypass
npm version's clean working tree check with--force.
- Verification & Tests Pass:
- All tests, typechecks, and linters must pass before cutting a version.
- Correct Branch:
- Confirm you are on the designated release branch (e.g.,
main,master, orrelease/*).
Versioning Commands & SemVer Selection
Choose the appropriate SemVer increment based on the nature of changes:
| Command | SemVer Level | When to Use | Example (1.0.0 -> ) |
|---|---|---|---|
npm version patch | PATCH | Backward-compatible bug fixes or minor patches | 1.0.1 |
npm version minor | MINOR | Backward-compatible new features or enhancements | 1.1.0 |
npm version major | MAJOR | Breaking changes, incompatible API modifications | 2.0.0 |
Pre-release Versioning
For alpha, beta, or release candidate iterations:
# Start pre-releases
npm version prepatch --preid=alpha # 1.0.0 -> 1.0.1-alpha.0
npm version preminor --preid=beta # 1.0.0 -> 1.1.0-beta.0
npm version premajor --preid=rc # 1.0.0 -> 2.0.0-rc.0
# Increment existing pre-release
npm version prerelease # 1.0.1-alpha.0 -> 1.0.1-alpha.1Custom Commit Message
To provide a descriptive commit message alongside the version bump:
npm version minor -m "Release %s: Add authentication module"(The `%s` placeholder is replaced with the newly generated version number).
Specific Target Version
To bump to an exact explicit version while retaining Git tag creation:
npm version 2.4.0NPM Lifecycle Hooks Integration
Take advantage of NPM's built-in version lifecycle hooks in package.json scripts:
{
"scripts": {
"preversion": "npm test && npm run lint",
"version": "npm run build && git add dist/",
"postversion": "git push && git push --tags"
}
}- `preversion`: Runs before the version is bumped. Use to enforce testing, linting, or changelog verification. If it fails, the version bump is aborted.
- `version`: Runs after
package.jsonis modified and staged, but before the Git commit and tag are created. Perfect for generating build artifacts, syncing changelogs, and staging them (git add CHANGELOG.md). - `postversion`: Runs after the Git commit and tag have been created. Ideal for pushing commits and tags to the remote repository.
Synchronizing with Remote
The npm version command creates the commit and tag locally. Always remember to push both to the remote repository:
git push && git push --tags
# Or using --follow-tags (pushes annotated tags on the current branch):
git push --follow-tagsDrift Detection & Remediation (Handling Manual Edits)
When inspecting a project, preparing a release, or reviewing changes, the agent must check whether the current "version" in package.json matches the latest Git version tag.
Detecting Drift
Run the following checks to identify if a manual version edit occurred:
- Uncommitted Version Edit:
- Check if
package.jsoncontains unstaged or staged modifications to"version":
git diff package.json- Missing or Mismatched Git Tag:
- Extract the current version from
package.json(e.g.,X.Y.Z). - Check if the matching Git tag exists and points to the appropriate commit:
git tag -l "vX.Y.Z"- If the tag does not exist or points to an older, unrelated commit, the version has drifted out of sync.
Remediation Workflows
If manual modification or tag desynchronization is detected, alert the user immediately and present the following two resolution options:
Option 1: Revert Manual Edit and Use npm version (Recommended)
This is the cleanest approach as it ensures standard NPM commit and tag generation.
- If the manual edit is uncommitted:
# 1. Discard manual changes in package manifests
git checkout HEAD -- package.json package-lock.json
# 2. Run the proper npm version command
npm version <patch|minor|major|X.Y.Z>- If the manual edit was committed locally (HEAD):
# 1. Undo the commit while keeping working files
git reset --soft HEAD~1
# 2. Discard the manual version edits
git checkout HEAD -- package.json package-lock.json
# 3. Apply the version bump through npm version
npm version <patch|minor|major|X.Y.Z>Option 2: Retroactively Synchronize Git Tag with Manual Version
Use this option if the manual change has already been pushed or must be preserved:
- Ensure lockfile is in sync:
npm install --package-lock-only- Commit manifest changes (if not yet committed):
git add package.json package-lock.json
git commit -m "vX.Y.Z"- Create the missing annotated Git tag:
git tag -a "vX.Y.Z" -m "vX.Y.Z"- Push commit and tag to remote:
git push && git push origin "vX.Y.Z"Agent Guardrails & Interception
When acting as an AI assistant:
- Intercept Manual Edits: If requested to "change the version to X", "bump version in package.json", or "prepare release", do NOT use file modification tools (
edit_fileorwrite_file) onpackage.jsonto alter"version". - Execute Terminal Command: Run
npm version <major|minor|patch|version>via the shell execution tool. - Detect & Alert on Drift: Whenever inspecting a repository before a release or build, verify if
package.jsonversion matches Git tags. If a manual edit or missing tag is detected:
- Alert the user proactively.
- Explain that
package.jsonand Git tags are out of sync. - Offer the two remediation paths (revert +
npm versionor create retroactive tag).
- Notify User: Clearly explain that
npm versionwas used to ensure synchronization betweenpackage.jsonand Git version tags.