A Complete Guide to Publishing Your First npm Package

January 1, 2025 (1y ago) · 3 min read

DevOps

Originally published on LinkedIn, 1 January 2025. Republished here with light editing.

Introduction#

Publishing a package to npm (Node Package Manager) is a crucial skill for JavaScript/TypeScript developers. This guide walks you through the complete process of publishing your first npm package, using a real-world example of publishing a Google News MCP Server project.

Prerequisites#

Before you start, ensure you have:

  • Node.js and npm installed on your system
  • A project ready to be published
  • Basic understanding of package.json
  • An npm account (create one at npmjs.com)

Step-by-Step Guide#

1. Preparing Your Project#

First, ensure your project has the correct structure and configuration. Your package.json file is crucial:

{
  "name": "@your-scope/package-name",
  "version": "1.0.0",
  "description": "Your package description",
  "main": "build/index.js",
  "files": [
    "build"
  ],
  "scripts": {
    "build": "tsc",
    "test": "jest"
  }
}

Important fields to configure:

  • name: Must include your scope for scoped packages
  • version: Follow semantic versioning
  • main: Entry point of your package
  • files: Specifies which files should be published

2. Setting Up Your npm Account#

  1. Create an account on npmjs.com
  2. Log in via CLI:
npm login

Follow the browser-based authentication process.

3. Understanding Scoped Packages#

Scoped packages use the format @scope-name/package-name. For personal accounts:

  • Scope name must match your npm username
  • Example: if your username is "johndoe", your scope would be "@johndoe"

4. Preparing for Publication#

  1. Remove "private": true from package.json if present
  2. Build your project:
npm run build
  1. Test your package:
npm test

5. Publishing Your Package#

For first-time publication of a scoped package:

npm publish --access public

If you want to publish as a private package (requires paid account):

npm publish --access restricted

6. Version Management#

After successful publication, manage versions using:

# Increment patch version (1.0.0 -> 1.0.1)
npm version patch
 
# Increment minor version (1.0.0 -> 1.1.0)
npm version minor
 
# Increment major version (1.0.0 -> 2.0.0)
npm version major

7. Package Updates#

To update your published package:

  1. Make your changes
  2. Update the version number
  3. Rebuild
  4. Publish again

Common Issues and Solutions#

1. Access Grant Error#

If you encounter:

npm error Cannot read properties of undefined (reading '0')

when running:

npm access grant read-write @scope/package-name

Solution: This error occurs when trying to set permissions for a non-existent package. You don't need to run this command for new packages. Simply use --access public when publishing.

2. Other Common Issues#

  • Package name already exists: Choose a different name or scope
  • Version already exists: Increment your version number
  • Publishing denied: Ensure you're logged in and have the correct permissions

Best Practices#

  1. Documentation Include a comprehensive README.md Document all features and usage examples Provide clear installation instructions
  2. Quality Assurance Add tests before publishing Test installation in a fresh directory Use npm pack to preview the published package
  3. Version Control Use semantic versioning Maintain a CHANGELOG.md Tag releases in git
  4. Package Configuration Keep package size minimal Configure .npmignore or use files in package.json Include appropriate keywords for discoverability

Using Your Published Package#

Others can install your package using:

npm install @your-scope/package-name

For our example MCP Server:

npm install @chanmeng666/google-news-server

Conclusion#

Publishing an npm package might seem daunting at first, but following these steps makes it a straightforward process. Remember to maintain your package with regular updates and clear documentation to provide value to your users.

Additional Resources#

LinkedIn