npm Publish Guide
This skill guides you through the process of publishing a package to the npm registry.
- Prerequisites
Before publishing, ensure you are logged in to npm.
npm whoami
If not logged in:
npm login
- 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
- 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
- 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
- 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