npm-publish_skill

Overview

This skill guides you through publishing packages to the npm registry. It covers prerequisites, package configuration, versioning, dry-run checks, scoped publishing, and post-publish verification. Use it to avoid common pitfalls and to make your release process repeatable and safe.

How this skill works

The skill inspects your package.json for critical fields (name, version, main/module/exports, files, private) and walks you through preparing build artifacts and excluding unnecessary files. It explains version bumping with npm version, performing npm publish --dry-run to preview the tarball, and the correct commands for publishing scoped or public packages. It also covers post-publish steps like pushing tags and verifying the published version.

When to use it

• Publishing a new package to the npm registry for the first time.
• Releasing a new version after code or build changes.
• Preparing a package that requires a build step (TypeScript, Babel, etc.).
• Ensuring only intended files are included in the published package.
• Publishing scoped packages publicly or managing access settings.

Best practices

• Confirm you're logged in with npm whoami before publishing.
• Keep package.json fields accurate: name, version, main/module/exports, files, and private.
• Use files or .npmignore to exclude tests, source, and config files; run npm publish --dry-run to verify.
• Run your build script (npm run build) before publishing compiled packages.
• Use npm version to update semver and create a git tag, then git push --follow-tags after publish.
• For scoped public packages include --access public on the first publish.

Example use cases

• Publishing a new utility library after compiling TypeScript to JavaScript.
• Releasing a patch version fix: npm version patch, npm publish, then push tags.
• Publishing a scoped organization package publicly: npm publish --access public.
• Verifying published output in a test project by running npm view <package-name> version and installing it locally.
• Reducing package size by listing only distributable files in package.json files array and confirming with a dry run.