How to Publish Your NPM Package: A Step-by-Step Guide
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
ornpm 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! ๐
Comments ()