alexbruno/dev-skills

npm-version-management

Enforce disciplined NPM package version management strictly via the npm version CLI.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/alexbruno/dev-skills --skill npm-version-management

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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:

  1. Updates Manifests: Safely bumps the "version" field in package.json and updates package-lock.json (preserving formatting and indentation).
  2. Creates a Git Commit: Stages the manifest changes and generates a dedicated release commit with a standardized message (default: v<version>).
  3. 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.json diverges 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:

  1. Clean Working Tree:
  • The Git working directory MUST be clean:
bash
     git status --porcelain
  • If uncommitted changes exist, commit or stash them first. Never bypass npm version's clean working tree check with --force.
  1. Verification & Tests Pass:
  • All tests, typechecks, and linters must pass before cutting a version.
  1. Correct Branch:
  • Confirm you are on the designated release branch (e.g., main, master, or release/*).

Versioning Commands & SemVer Selection

Choose the appropriate SemVer increment based on the nature of changes:

CommandSemVer LevelWhen to UseExample (1.0.0 -> )
npm version patchPATCHBackward-compatible bug fixes or minor patches1.0.1
npm version minorMINORBackward-compatible new features or enhancements1.1.0
npm version majorMAJORBreaking changes, incompatible API modifications2.0.0

Pre-release Versioning

For alpha, beta, or release candidate iterations:

bash
# 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.1

Custom Commit Message

To provide a descriptive commit message alongside the version bump:

bash
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:

bash
npm version 2.4.0

NPM Lifecycle Hooks Integration

Take advantage of NPM's built-in version lifecycle hooks in package.json scripts:

json
{
  "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.json is 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:

bash
git push && git push --tags
# Or using --follow-tags (pushes annotated tags on the current branch):
git push --follow-tags

Drift 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:

  1. Uncommitted Version Edit:
  • Check if package.json contains unstaged or staged modifications to "version":
bash
     git diff package.json
  1. 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:
bash
     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:
bash
  # 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):
bash
  # 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:

  1. Ensure lockfile is in sync:
bash
   npm install --package-lock-only
  1. Commit manifest changes (if not yet committed):
bash
   git add package.json package-lock.json
   git commit -m "vX.Y.Z"
  1. Create the missing annotated Git tag:
bash
   git tag -a "vX.Y.Z" -m "vX.Y.Z"
  1. Push commit and tag to remote:
bash
   git push && git push origin "vX.Y.Z"

Agent Guardrails & Interception

When acting as an AI assistant:

  1. 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_file or write_file) on package.json to alter "version".
  2. Execute Terminal Command: Run npm version <major|minor|patch|version> via the shell execution tool.
  3. Detect & Alert on Drift: Whenever inspecting a repository before a release or build, verify if package.json version matches Git tags. If a manual edit or missing tag is detected:
  • Alert the user proactively.
  • Explain that package.json and Git tags are out of sync.
  • Offer the two remediation paths (revert + npm version or create retroactive tag).
  1. Notify User: Clearly explain that npm version was used to ensure synchronization between package.json and Git version tags.
같은 저장소의 Skills

더 많은 Skills

모든 Skills
alexbruno
커뮤니티

architect-worker

Role-based multi-agent software engineering pattern separating high-level architecture, specification, planning, and code review (Architect) from focused code implementation and verification (Worker). Use this skill whenever assigned the Architect or Worker role (in any language), or when coordinating work between planning/review agents and implementation agents via workflow/.

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 13일
alexbruno
커뮤니티

changelog-management

Maintain and update a standardized root CHANGELOG.md following Keep a Changelog and Semantic Versioning. Use this skill to initialize or update changelog entries, categorize changes, prepare release cuts, and proactively prompt the user when notable changes warrant updating the changelog.

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 13일
alexbruno
커뮤니티

code-review

Perform structured, multi-dimensional code reviews aligned with the spec-driven-workflow (workflow/SPEC.md, workflow/PLAN.md, workflow/REVIEW.md). Use this skill after implementing a feature or bug fix, before merging a PR, or when reviewing changes written by another agent or human.

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 13일
alexbruno
커뮤니티

code-simplification

Simplify code for human readability, clarity, and directness without changing behavior. Use this skill after implementing a feature, during refactoring, or when addressing code review feedback—especially when code feels over-engineered, deeply nested, or takes unnecessary detours to do simple things.

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 13일