How to Publish Your NPM Package: A Step-by-Step Guide

How to Publish Your NPM Package: A Step-by-Step Guide
Photo by Zosia Szopka / Unsplash

Publishing an NPM package can sometimes feel like a daunting task, especially if it's been a while since your last release. If you're maintaining a package like sshmgr (an imaginary package name), and you've recently updated dependencies or added new features, it's time to publish a new version. Hereโ€™s a complete guide to ensure a smooth publishing process.


๐Ÿ“Œ Step 1: Update the Version

Since youโ€™ve made significant updates (such as upgrading dependencies), follow semantic versioning (SemVer) to properly bump your version number.

For example, if your current version is 0.2.4 and you've made non-breaking changes and improvements, increase the minor version:

npm version 0.3.0

This command will:

  • Update the version in your package.json
  • Create a Git tag for v0.3.0

โœ… Tip: If youโ€™re making small fixes, increase the patch version (0.2.4 โ†’ 0.2.5). If you introduce breaking changes, bump the major version (1.0.0).


๐Ÿ“Œ Step 2: Build the Package

Your project is using TypeScript and tsup for building. Before publishing, make sure your code is properly compiled:

npm run build

This ensures that the dist/ folder contains the latest compiled JavaScript files.

โœ… Tip: Double-check that your package.json points to the correct entry file:

"main": "./dist/index.js",
"bin": {
  "sshmgr": "./dist/index.js"
}

(Note: sshmgr is an imaginary package name for this guide.)


๐Ÿ“Œ Step 3: Login to NPM

If you haven't logged in to NPM recently, you may need to authenticate:

npm login

Youโ€™ll be prompted to enter your NPM username, password, and email.

โœ… Tip: If you're using 2FA (two-factor authentication), you'll need to enter an authentication code from your NPM account.


๐Ÿ“Œ Step 4: Verify Before Publishing

Before publishing, you can preview what will be published by running:

npm pack

This will create a .tgz package file, simulating the publishing process. You can inspect the contents to ensure everything looks correct.

โœ… Common Mistakes to Check:

  • Ensure that the dist/ directory exists and contains the built files.
  • Confirm that unwanted files (like .git, node_modules, or .env) are ignored in .npmignore.
  • Run npm list --prod to check installed dependencies.

๐Ÿ“Œ Step 5: Publish the Package

Once you're confident everything is correct, publish your package:

npm publish --access public

This will upload your package to the npm registry.

โœ… Important Considerations:

  • If your package is scoped (e.g., @yourname/sshmgr), you must use --access public.
  • If you get a permission error, ensure youโ€™re the package owner on npm.
  • If you get an already published version error, update the version with npm version patch or npm version minor.

๐Ÿ“Œ Step 6: Verify the Published Package

After publishing, confirm that the new version is available:

npm view sshmgr version

Or check it directly on npm: ๐Ÿ”— https://www.npmjs.com/package/sshmgr

โœ… Tip: If you find an issue after publishing, you can deprecate the version with:

npm deprecate [email protected] "This version has a bug, please use 0.3.1"

๐Ÿ“Œ Step 7: Push the Changes to GitHub

To keep your repository in sync with the new version, push your changes and tag:

git add package.json package-lock.json
git commit -m "Bump version to 0.3.0"
git push origin main
git push origin v0.3.0

โœ… Tip: If you use GitHub Actions for automated publishing, make sure your workflow is triggered by the new tag.


๐ŸŽ‰ Finally

Congratulations! Your updated package is now published and available for everyone to use. ๐ŸŽ‰

Checklist Before Publishing: โœ… โœ” Version updated (npm version) โœ” Package built (npm run build) โœ” Logged in to npm (npm login) โœ” Verified package contents (npm pack) โœ” Successfully published (npm publish) โœ” Checked the live version (npm view sshmgr version) โœ” Pushed changes to GitHub (git push)

Now your package [email protected] is officially live! ๐Ÿš€

Support Us