tomevault-io 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 statusto 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 statusandgit 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.