NPM Publisher

Overview

This skill provides a complete workflow for publishing npm packages with automated CI/CD. It handles version bumping, git tagging, and triggering automated npm publishing through GitHub Actions.

Release Workflow

Follow this workflow when releasing a new version with unstaged changes:

Step 1: Stage All Changes

Stage all pending changes:

git add .

Step 2: Commit the Changes

Commit with a meaningful message describing what changed:

git commit -m "$(cat <<'EOF' <Description of changes>

<Optional: more details> EOF )"

Important: Never add attributions to a coding agent in commit messages.

Step 3: Determine Version Type

Ask the user which type of version bump is appropriate, or infer from the changes:

• patch - Bug fixes (3.0.2 → 3.0.3)

• minor - New features (3.0.3 → 3.1.0)

• major - Breaking changes (3.1.0 → 4.0.0)

If unclear, analyze the git diff to determine the appropriate version type based on:

• Bug fixes only → patch

• New features without breaking changes → minor

• Breaking changes or major refactors → major

Step 4: Bump Version

Bump the version using npm:

npm version <patch|minor|major>

This command will:

• Increment the version in package.json

• Create a git commit with the version bump

• Create a git tag (e.g., v3.0.3)

Step 5: Push Commits and Tags

Push both commits and tags to the remote repository:

git push && git push --tags

Step 6: Verify Publishing

After pushing, publishing happens automatically through CI/CD:

• GitHub Actions automatically publishes to npm when a new tag is pushed

• Wait approximately 30 seconds for CI to complete

• Verify the release succeeded:

gh run list --limit 1

Step 7: Test the New Version

After CI completes successfully, verify the published version:

Clear npx cache if needed

npx clear-npx-cache

Test the new version (replace 'universal-skills' with the actual package name)

npx <package-name> --version

Error Handling

Common Issues

Uncommitted changes error:

• Ensure all changes are committed before running npm version

• Use git status to check for uncommitted changes

Push rejected:

• Pull latest changes with git pull --rebase

• Resolve any conflicts

• Retry the push

CI/CD failure:

• Check GitHub Actions logs: gh run view --log

• Common causes: failing tests, missing credentials, npm registry issues

• Fix the issue and create a new patch release if needed

Version already exists:

• Check if the version was already published: npm view <package-name> versions

• Bump to the next version if needed

Best Practices

• Always review changes before publishing with git status and git diff

• Run tests before publishing to catch issues early

• Write meaningful commit messages that explain the "why" not just the "what"

• Use semantic versioning consistently to manage user expectations

• Verify the release by testing the published package

Pre-Release Checklist

Before starting the release workflow, ensure:

• All tests pass

• Build succeeds without errors

• Breaking changes are documented

• Dependencies are up to date

• No sensitive information in commits