npm-publishing

Use when publishing npm packages - covers package.json configuration, versioning, and provenance

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill serves as a comprehensive guide and automation template for publishing npm packages. It streamlines the release process by ensuring best practices in package.json configuration, semantic versioning, and secure publishing with provenance, helping developers maintain high-quality software delivery pipelines.

Use Cases

  • Standardizing package.json configurations for modern JavaScript projects, including ESM/CJS exports and metadata optimization.
  • Managing semantic versioning (SemVer) workflows to ensure consistent and predictable package updates.
  • Implementing secure publishing practices using npm provenance to verify build authenticity and improve supply chain security.
  • Setting up pre-publish validation scripts and 'dry-run' checks to prevent broken or incomplete releases to the npm registry.
namenpm-publishing
descriptionUse when publishing npm packages - covers package.json configuration, versioning, and provenance

npm Publishing Best Practices

Quick Start

{
  "name": "lea-lang",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build && npm test"
  }
}

Package Configuration

Essential Fields

{
  "name": "lea-lang",
  "version": "1.1.3",
  "description": "Pipe-oriented functional programming language",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "lea": "./dist/cli/index.js"
  },
  "files": [
    "dist",
    "README.md"
  ],
  "keywords": ["language", "interpreter", "functional", "pipes"],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/lea.git"
  },
  "engines": {
    "node": ">=18"
  }
}

Exports (Modern)

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    },
    "./parser": {
      "types": "./dist/parser.d.ts",
      "import": "./dist/parser.mjs",
      "require": "./dist/parser.js"
    }
  }
}

Versioning

Semantic Versioning

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  # Patch: bug fixes
1.0.1 → 1.1.0  # Minor: new features (backwards compatible)
1.1.0 → 2.0.0  # Major: breaking changes

Version Commands

npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0

Publishing

First-Time Setup

npm login
npm publish --access public  # For scoped packages
npm publish --provenance --access public

Dry Run

npm publish --dry-run
npm pack  # Creates tarball to inspect

Files to Include/Exclude

.npmignore

src/
__tests__/
tests/
*.test.ts
.github/
docs/

Or use package.json "files"

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

Pre-publish Checks

{
  "scripts": {
    "prepublishOnly": "npm run build && npm test && npm run lint"
  }
}

Reference Files