A Guide to Publishing Your Own npm Package

1. Creating an npm Account

First, you need to register and create an account on the npm website:

1. Visit the official npm website: www.npmjs.com and register a new account
2. After registration, you’ll be directed to your new homepage with prompts to:
   • Enable Two-Factor Authentication (2FA): While recommended for security, this is optional and requires an authentication app
   • Verify your email address: Click on the prompt to receive a verification email, then follow the instructions in your inbox

2. Creating Your npm Package

Let’s create a simple utility package as an example:

1. Create a new folder for your package (e.g., my-utils)
2. Navigate to the folder in your terminal and run npm init
3. You’ll be prompted to enter configuration details - press Enter to accept defaults or enter your own values
4. This process generates a package.json file, which you can always modify later

Here’s a sample package.json file:

{
  "name": "my-utils",           // Package name (must be unique)
  "version": "1.0.0",           // Version number
  "author": "Your Name",        // Author information
  "description": "Common toolkit for everyday tasks", // Description
  "keywords": ["utils", "format", "money", "phone"], // Keywords for SEO
  "repository": {               // Code repository location
    "type": "git",
    "url": "https://github.com/yourusername/my-utils"
  },
  "license": "MIT",             // License type
  "homepage": "https://your-package.org", // Package homepage
  "bugs": "https://github.com/yourusername/my-utils/issues", // Issue reporting URL
  "main": "index.js",           // Entry point file
  "scripts": {                  // Executable scripts
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "dependencies": {},           // Runtime dependencies
  "devDependencies": {}         // Development dependencies
}

3. Creating Package Files

This part depends on your project.

4. Uploading to GitHub (Optional but Recommended)

1. Create a new repository on GitHub called my-utils
2. Initialize and push your local project to GitHub:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:yourusername/my-utils.git
git push -u origin main

5. Publishing Your npm Package

Check npm Registry Source

Before publishing, make sure you’re using the official npm registry:

# Check current npm registry
npm config get registry

# Set to official npm registry if needed
npm config set registry https://registry.npmjs.org/

Note: If you normally use a mirror like the npmmirror.com (formerly npm.taobao.org), remember to switch back to the official registry before publishing.

Login to npm

In your project directory, run:

npm login

Follow the prompts to enter your:

• Username
• Password
• Email address
• One-time password (if you have 2FA enabled)

You should see confirmation: Logged in as yourusername on https://registry.npmjs.org/.

Publish Your Package

Once logged in, simply run:

npm publish

--access public

If successful, your package will be available on npm for anyone to install!

6. Using Your Published Package

Others can now install your package:

npm install my-utils

And use it in their projects:

import { Format, Validate } from 'my-utils';

// Check if a phone number is valid
const isValid = Validate.mobileCheck('13812345678');

// Format a number as currency
const formattedPrice = Format.formatMoney(12345.67, '$');

7. Updating Your Package

When you need to update your package:

1. Make your code changes
2. Update the version in package.json following semantic versioning:
   • Increment the patch version for bug fixes (1.0.0 → 1.0.1)
   • Increment the minor version for new features (1.0.1 → 1.1.0)
   • Increment the major version for breaking changes (1.1.0 → 2.0.0)
3. Run npm publish again

You can also use npm’s version commands:

npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.1 → 1.1.0
npm version major  # 1.1.0 → 2.0.0

Common Issues and Solutions

• Package name already exists: Choose a unique name or use a scoped package with your username (@yourusername/my-utils)
• Insufficient permissions: Make sure you’re properly logged in with npm login
• Version conflict: You cannot publish the same version twice, ensure you update your version number
• Files not included: Check your .npmignore or files field in package.json to ensure necessary files are included

Best Practices

1. Document your package: Include a good README.md with installation instructions and examples
2. Write tests: Include tests to validate your package functionality
3. Use semantic versioning: Follow proper versioning to communicate changes
4. Include TypeScript definitions: If applicable, provide proper type definitions
5. Set up CI/CD: Automate testing and publishing with GitHub Actions or similar tools

Happy publishing!