npm Publish Guide

This skill guides you through the process of publishing a package to the npm registry.

1. Prerequisites

Before publishing, ensure you are logged in to npm.

npm whoami

If not logged in:

npm login

2. Preparation & Configuration

Critical package.json Fields

Ensure these fields are correct:

• name: Unique package name (scoped names like @org/pkg are recommended for organizations).
• version: SemVer compliant version (e.g., 1.0.0).
• main/module/exports: Entry points for your library.
• files: Whitelist of files to include (reduces package size).
• private: Must be false (or missing) to publish.

Excluding Files

Use a .npmignore file or the files array in package.json to prevent publishing unnecessary files (tests, src, config files). Tip: npm publish --dry-run shows exactly what will be packed.

Build (If applicable)

If your package requires compilation (TypeScript, Babel, etc.), run the build script first.

npm run build

3. Versioning

Update the package version before publishing. This command increments the version in package.json and creates a git tag.

# Choose one:
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

4. Publishing

Dry Run

Always do a dry run first to verify contents.

npm publish --dry-run

Scoped Packages

If publishing a scoped package (e.g., @myorg/my-pkg) publicly for the first time:

npm publish --access public

Standard Publish

npm publish

5. Post-Publish

Push Tags

Push the new version commit and tags to your git repository.

git push --follow-tags

Verification

Check the npm registry or install the package in a test project to verify.

npm view <package-name> version