Node.js NPM Auto Release

Overview

Provide a repeatable workflow to prepare, verify, and ship npm packages with a combined auto-version-and-publish GitHub Action, plus local checks before push.

Setup Checklist

1. Add release scripts in package.json

{
  "scripts": {
    "release:patch": "npm version patch -m \"chore(release): v%s\"",
    "release:minor": "npm version minor -m \"chore(release): v%s\"",
    "release:major": "npm version major -m \"chore(release): v%s\""
  }
}

1. Add .npmignore to keep packages clean

Typical entries:

• .github/
• .claude/
• docs/
• tests/
• .env
• node_modules/

1. Add the combined workflow file

Create .github/workflows/auto-version-publish.yml with:

name: auto version and publish

on:
  push:
    branches:
      - main

permissions:
  contents: write
  id-token: write

jobs:
  release:
    if: ${{ !contains(github.event.head_commit.message, 'chore(release):') }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
          registry-url: "https://registry.npmjs.org"

      - name: Install dependencies
        run: |
          npm ci

      - name: Typecheck
        run: |
          npm run typecheck

      - name: Test
        run: |
          npm test

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Bump patch version and tag
        run: |
          npm version patch -m "chore(release): v%s [skip ci]"

      - name: Push version bump and tag
        run: |
          git push origin HEAD:main --follow-tags

      - name: Publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: |
          npm publish --access public

1. Set GitHub secret

Add NPM_TOKEN in repo Secrets with publish permission.

Release Workflow

1. Local checks

npm run typecheck
npm test
npm pack --dry-run

1. Commit and push

git add -A
git commit -m "feat: update package"
git push origin main

1. Verify release

• Ensure auto version and publish workflow succeeds
• Confirm new tag created
• Confirm npm version:

npm view <package-name> version

Notes

• Auto-release skips commits containing chore(release): to avoid loops.
• If you need manual bump, use npm run release:patch then push tags.