Skip to content

NPM_PUBLISH_GUIDE.md

Latest commit

 

History

History
231 lines (147 loc) · 3.83 KB

NPM_PUBLISH_GUIDE.md

File metadata and controls

231 lines (147 loc) · 3.83 KB

📦 NPM Publishing Guide

Follow these steps to publish your CLI to npm:

🔐 Step 1: Create/Login to npm Account

If you don't have an npm account:

  1. Go to https://www.npmjs.com/signup
  2. Create a free account
  3. Verify your email

Login to npm via CLI:

npm login

Enter your:

  • Username
  • Password
  • Email
  • One-time password (if 2FA is enabled)

Verify you're logged in:

npm whoami

📝 Step 2: Check Package Name Availability

The package name is: createx

Check if it's available:

npm search createx

Or check on: https://www.npmjs.com/package/createx

✅ Good news: createx is available and ready to use!

🧪 Step 3: Test Locally

Test your CLI works before publishing:

# Install dependencies
npm install

# Test the CLI
node index.js

# Link it globally to test the bin command
npm link

# Test the global command
initgen

# Unlink when done testing
npm unlink -g initgen

🚀 Step 4: Publish to npm

Dry run (see what will be published):

npm publish --dry-run

Publish:

npm publish

✅ Step 5: Verify Publication

  1. Check on npm: https://www.npmjs.com/package/createx
  2. Wait 2-5 minutes for indexing
  3. Test installation:
# Install globally
npm install -g createx

# Or use npx (no installation needed)
npx createx

🔄 Step 6: Updating Your Package

When you make changes and want to publish a new version:

Update version:

# Patch version (1.0.0 -> 1.0.1) - for bug fixes
npm version patch

# Minor version (1.0.0 -> 1.1.0) - for new features
npm version minor

# Major version (1.0.0 -> 2.0.0) - for breaking changes
npm version major

Publish the update:

npm publish --access public

📊 Package Commands

After publishing, users can install your CLI:

# Install globally
npm install -g initgen

# Run with npx (no installation)
npx initgen

# Or use the command
initgen

🎯 Important Notes

  1. Scoped Packages: Packages like @pankajkumardev/... are scoped to your username

    • Free for public packages
    • Require --access public flag when publishing

  2. Version Numbers: Follow semantic versioning

    • MAJOR.MINOR.PATCH (e.g., 1.0.0)

    • Can't publish the same version twice

    • MAJOR.MINOR.PATCH (e.g., 1.0.0)

    • Can't publish the same version twice

  3. Package Size: Keep it under 10MB if possible

    • Check size: npm pack --dry-run

  4. README: Your README.md will be the package homepage on npm

  5. Keywords: Good keywords help users find your package

🐛 Troubleshooting

"Package name already exists"

  • Use a scoped package: @yourusername/package-name
  • Choose a different unique name

"You must verify your email"

  • Check your email and verify your npm account

"You need to authenticate"

  • Run npm login again

"402 Payment Required"

  • You're trying to publish a private scoped package
  • Add --access public flag

"403 Forbidden"

  • You don't have permission to publish under this name
  • The package might be owned by someone else

🌟 After Publishing

  1. Share on Twitter/LinkedIn

  2. Add npm badge to README:

    ![npm version](https://img.shields.io/npm/v/createx.svg)
![npm downloads](https://img.shields.io/npm/dm/createx.svg)

  3. Track downloads: https://npm-stat.com/charts.html?package=createx

  4. Monitor issues on GitHub

  5. Keep package updated

📝 Quick Command Reference

# Login
npm login

# Test locally
npm link

# Check what will be published
npm publish --dry-run

# Publish
npm publish

# Update version
npm version patch

# View package info
npm info createx

# Unpublish (within 72 hours)
npm unpublish createx@1.0.0

Ready to publish? Run these commands:

npm login
npm publish

🎉 That's it! Your CLI will be live on npm!