# A Complete Guide to Publishing Your First npm Package

> Publishing a first package to npm, using a real Google News MCP Server release as the example: package.json preparation, account setup, scoped-package access flags, versioning, updates, and the errors that trip people up.

Source: https://chanmeng.org/blog/publishing-your-first-npm-package
Author: Chan Meng — https://chanmeng.org
Published: 2025-01-01
Tags: 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](http://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:

```json
{
  "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](http://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:

```bash
npm run build
```

1. Test your package:

```
npm test
```

### 5. Publishing Your Package

For first-time publication of a scoped package:

```bash
npm publish --access public
```

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

```bash
npm publish --access restricted
```

### 6. Version Management

After successful publication, manage versions using:

```bash
# 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:

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

when running:

```bash
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:

```bash
npm install @your-scope/package-name
```

For our example MCP Server:

```bash
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

- [npm Documentation](https://docs.npmjs.com/)
- [Semantic Versioning](https://semver.org/)
- [Package.json guide](https://docs.npmjs.com/cli/v7/configuring-npm/package-json)
- [npm Best Practices](https://www.npmjs.com/policies/npm-best-practices)