DEV Community

yao tang
yao tang

Posted on

How to Publish Your First NPM Package: A Complete Guide

#node #npm #ai

Publishing your first NPM package can seem daunting, but it's actually straightforward once you know the steps. In this guide, I'll walk you through the entire process, including how to solve common issues like registry configuration problems.

Prerequisites

  • Node.js and npm installed
  • A project ready to publish
  • An NPM account (create one at npmjs.com)

Step 1: Check Package Name Availability

Before you start, make sure your desired package name isn't already taken:

npm search your-package-name
Enter fullscreen mode Exit fullscreen mode

If the name is taken, you have several options:

  • Use a scoped package: @yourusername/package-name
  • Choose a different name
  • Add descriptive prefixes/suffixes

For example, if "testpilot" is taken, you could use "ai-testpilot" or "@yourusername/testpilot".

Step 2: Configure Your package.json

Make sure your package.json has all the required fields:

{
  "name": "your-package-name",
  "version": "1.0.0",
  "description": "What your package does",
  "main": "index.js",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourusername/your-repo.git"
  },
  "keywords": ["keyword1", "keyword2"],
  "author": "Your Name",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/yourusername/your-repo/issues"
  },
  "homepage": "https://github.com/yourusername/your-repo#readme"
}
Enter fullscreen mode Exit fullscreen mode

For CLI tools, add a bin field:

{
  "bin": {
    "your-command": "./bin/cli.js"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Fix Registry Configuration (Important!)

This is where many people get stuck. If you're using a mirror like Taobao or npmmirror, you need to switch back to the official NPM registry for publishing.

Check your current registry:

npm config get registry
Enter fullscreen mode Exit fullscreen mode

If it shows anything other than https://registry.npmjs.org/, fix it:

npm config set registry https://registry.npmjs.org/
Enter fullscreen mode Exit fullscreen mode

Common problematic registries:

  • https://registry.npmmirror.com/ (Alibaba mirror)
  • https://registry.npm.taobao.org/ (Taobao mirror)
  • Company internal registries

Step 4: Login to NPM 

npm login
Enter fullscreen mode Exit fullscreen mode

You'll be prompted for:

  • Username
  • Password
  • Email address

Verify you're logged in:

npm whoami
Enter fullscreen mode Exit fullscreen mode

Step 5: Prepare for Publishing

Create .npmignore (optional):

node_modules/
.git/
.DS_Store
*.log
test/
.env
Enter fullscreen mode Exit fullscreen mode

If you're using TypeScript, build first:

npm run build
Enter fullscreen mode Exit fullscreen mode

Test your package locally:

npm pack
npm install -g your-package-name-1.0.0.tgz
# Test your package
npm uninstall -g your-package-name
rm your-package-name-1.0.0.tgz
Enter fullscreen mode Exit fullscreen mode

Step 6: Publish! 

npm publish
Enter fullscreen mode Exit fullscreen mode

For scoped packages, make them public:

npm publish --access public
Enter fullscreen mode Exit fullscreen mode

Step 7: Verify Publication

Check on NPM website:
Visit https://npmjs.com/package/your-package-name

Search for your package:

npm search your-package-name
Enter fullscreen mode Exit fullscreen mode

Test installation:

npm install your-package-name
Enter fullscreen mode Exit fullscreen mode

Common Issues and Solutions

"Package name already exists"

  • Use a scoped package: @yourusername/package-name
  • Choose a different name
  • Check if the existing package is abandoned (contact NPM support)

"Public registration is not allowed"

  • You're trying to publish to a private registry (like CNPM)
  • Fix your registry configuration (Step 3)

"You do not have permission to publish"

  • Make sure you're logged in: npm whoami
  • Check if you're trying to publish to the correct registry
  • For scoped packages, use --access public

"Avatar not updating"

  • NPM uses Gravatar for avatars
  • Link your NPM email to a Gravatar account
  • Clear browser cache and wait for synchronization

Pro Tips

  1. Version Management: Use semantic versioning (major.minor.patch)
  2. Add a README: Include installation and usage instructions
  3. Keywords: Add relevant keywords for better discoverability
  4. License: Always specify a license (MIT is popular)
  5. Automated Publishing: Consider using GitHub Actions for CI/CD

Updating Your Package

When you need to update:

  1. Make your changes
  2. Update the version in package.json
  3. Run npm publish again 
# Quick version bump
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
npm publish
Enter fullscreen mode Exit fullscreen mode

Conclusion

Publishing to NPM is straightforward once you understand the process. The most common stumbling block is registry configuration - always make sure you're pointing to the official NPM registry when publishing.

Your package is now available for the entire Node.js community to use. Congratulations on your first NPM publication! 🎉

Have you published your first NPM package? Share your experience in the comments below!

Top comments (0)