# Reference for publishing NPM packages

# Introduction

A reference for myself. Hence the use of pnpm which I use most of the time. 🤷

# 1\. Initial Setup

```bash
# Initialize package
pnpm init
# Set up typescript, tests, etc
pnpm add -D typescript tsup vitest ... etc

# Setup GitHub repo
git init
git add .
git commit -m "Initial commit"
git remote add origin <repo-url>
git push -u origin main
```

# 2\. Pre-publish Checklist

```bash
# Update package.json
{
  "name": "@yourscope/package-name",
  "version": "1.0.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "test": "vitest",
    "prepublishOnly": "pnpm test && pnm build"
  }
}

# Login to npm (one-time)
pnpm login
```

# 3\. Publishing Process

```bash
# Version bump (automatically creates git tag)
pnpm version patch  # 0.0.1 -> 0.0.2
# or
pnpm version minor  # 0.0.1 -> 0.1.0
# or
pnpm version major  # 0.0.1 -> 1.0.0

# Push code and tags
git push
git push --tags

# Publish to npm
pnpm publish --access public  # --access public only needed first time for scoped packages
```

# 4\. GitHub Release

* Go to GitHub after pushing tags
    
* Releases &gt; Draft new release
    
* Choose the tag
    
* Write release notes
    
* Publish release
    

# 5\. Subsequent Releases

```bash
# Make changes
git commit -m "feat: new feature"

# Version and publish
pnpm version minor
git push && git push --tags
pnpm publish

# Create GitHub release
```

# Common Version Types

* `patch`: Bug fixes (1.0.0 -&gt; 1.0.1)
    
* `minor`: New features, backward compatible (1.0.0 -&gt; 1.1.0)
    
* `major`: Breaking changes (1.0.0 -&gt; 2.0.0)
    

# Best Practices

* Always run tests before publishing
    
* Keep consistent version numbers between git tags and npm
    
* Write clear release notes
    
* Consider semantic versioning (semver)
    
* Use a .npmignore or files array to control published contents
    
* Set up CI/CD for automated testing/publishing
    

This workflow ensures:

1. Version control is in sync with package versions
    
2. Changes are properly documented
    
3. Package is tested before publishing
    
4. GitHub and npm stay in sync