npm Package Publishing Checklist

src/
test/
tests/
__tests__/
*.test.js
*.spec.js
*.ts
!*.d.ts
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
.github/
.git/
.vscode/
*.log
.DS_Store
coverage/
.nyc_output/
docs/
examples/
.env
.env.*

# Check what will be included in the package
npx npm-packlist

# Dry run — see exactly what npm publish would do
npm publish --dry-run

# Verify package contents after packing
npm pack
tar -tzf *.tgz
rm *.tgz

# Check for missing or incorrect fields
npx @npmcli/package-json lint

# Audit dependencies for vulnerabilities
npm audit

# Run your full test suite
npm test

# Ensure build passes
npm run build

# Login to npm (opens browser)
npm login

# Verify you're logged in
npm whoami

# Check 2FA status
npm profile get two-factor-auth

# First publish (scoped package must be public explicitly)
npm publish --access public

# Subsequent publishes after version bump
npm publish

# Publish with 2FA
npm publish --otp=123456

# Publish a scoped package privately (requires paid plan)
npm publish --access restricted

# Publish to a specific tag (not latest)
npm publish --tag next
npm publish --tag beta

# Publish under an org scope
npm publish --access public

# Init a scoped package
npm init --scope=@my-org

# Verify org membership
npm org ls my-org

# Verify package on registry
npm view my-package

# Install and test from registry
npx create-my-package  # if CLI
npm install my-package # if library

# Check download counts
npm info my-package

# Tag a release after publish
git tag v1.0.0
git push --tags

# Create a tarball without publishing
npm pack

# Pack and inspect contents
npm pack && tar -tzf *.tgz

# Pack dry run
npm pack --dry-run --json

# Install from local tarball
npm install ./my-package-1.0.0.tgz

# Patch release (1.0.0 → 1.0.1) — bug fixes
npm version patch

# Minor release (1.0.0 → 1.1.0) — new features, backward compatible
npm version minor

# Major release (1.0.0 → 2.0.0) — breaking changes
npm version major

# Pre-release versions
npm version prerelease          # 1.0.0 → 1.0.1-0
npm version prepatch            # 1.0.0 → 1.0.1-0
npm version preminor            # 1.0.0 → 1.1.0-0
npm version premajor            # 1.0.0 → 2.0.0-0

# With explicit pre-release identifier
npm version prerelease --preid=alpha   # 1.0.0 → 1.0.1-alpha.0
npm version prerelease --preid=beta    # 1.0.1-beta.0
npm version prerelease --preid=rc      # 1.0.1-rc.0

# Set exact version
npm version 2.1.3

# Version bump without git commit/tag
npm version patch --no-git-tag-version

# Bump then publish in one line
npm version patch && npm publish

# List all dist-tags for a package
npm dist-tag ls my-package

# Add a dist-tag to a specific version
npm dist-tag add my-package@1.2.0 beta

# Remove a dist-tag
npm dist-tag rm my-package beta

# Publish directly to a tag
npm publish --tag next
npm publish --tag beta
npm publish --tag experimental

# Promote from beta to latest
npm dist-tag add my-package@2.0.0-beta.3 latest

# Deprecate a specific version with a message
npm deprecate my-package@1.0.0 "Security vulnerability, upgrade to 1.0.1"

# Deprecate all versions below a certain range
npm deprecate my-package@"< 2.0.0" "Please upgrade to v2"

# Deprecate entire package
npm deprecate my-package "This package is no longer maintained. Use @my-org/new-package instead."

# Deprecate with OTP
npm deprecate my-package@1.0.0 "Deprecated" --otp=123456

# Unpublish a specific version (within 72 hours)
npm unpublish my-package@1.0.0

# Unpublish entire package (within 72 hours)
npm unpublish my-package --force

# Unpublish with OTP
npm unpublish my-package@1.0.0 --otp=123456

MAJOR.MINOR.PATCH

PATCH  — Bug fixes, no API changes          1.0.0 → 1.0.1
MINOR  — New features, backward compatible   1.0.0 → 1.1.0
MAJOR  — Breaking changes                    1.0.0 → 2.0.0

Pre-release:  1.0.0-alpha.0 < 1.0.0-alpha.1 < 1.0.0-beta.0 < 1.0.0-rc.0 < 1.0.0
Build:        1.0.0+build.123  (ignored for precedence)

Caret (^):    ^1.2.3  → >=1.2.3 <2.0.0   (compatible with)
Tilde (~):    ~1.2.3  → >=1.2.3 <1.3.0   (approximately)
Exact:        1.2.3   → exactly 1.2.3
Any:          *       → any version

Range examples:
  >=1.0.0 <2.0.0
  1.2.x
  ~1.2.3
  ^0.2.3   → >=0.2.3 <0.3.0  (0.x caret behavior)

name: Publish to npm
on:
  release:
    types: [published]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}