Publishing Packages

Publishing to npm lets you share your code with the world. Let's learn how to create and publish your own packages.

Prerequisites

Before publishing, you need:

1. An npm account (register at npmjs.com)
2. A package ready to publish
3. npm CLI logged in

# Log in to npm
npm login

# Verify you're logged in
npm whoami

Preparing Your Package

Required package.json Fields

{
  "name": "my-unique-package",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

Recommended Fields

{
  "name": "my-unique-package",
  "version": "1.0.0",
  "description": "A useful package that does something",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "keywords": ["useful", "package"],
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/you/my-package"
  },
  "homepage": "https://github.com/you/my-package#readme",
  "bugs": "https://github.com/you/my-package/issues"
}

Package Naming

Public Packages

Must be unique across all of npm:

{
  "name": "cool-utility"
}

Scoped Packages

Use your username or organization:

{
  "name": "@yourusername/cool-utility"
}

Scoped packages can be:

• Public (free)
• Private (requires npm paid plan)

Controlling What Gets Published

Using files Field

Whitelist files to include:

{
  "files": [
    "dist",
    "README.md"
  ]
}

Using .npmignore

Blacklist files to exclude:

# .npmignore
src/
tests/
.github/
*.test.js

Default Exclusions

npm always ignores:

• .git
• node_modules
• .npmrc
• Files in .gitignore

Check What Will Be Published

npm pack --dry-run

This shows exactly what files will be included.

Publishing Steps

1. Build Your Package

npm run build

2. Test Locally

# Create a tarball
npm pack

# Install in another project
npm install ../path/to/my-package-1.0.0.tgz

3. Publish

# For public packages
npm publish

# For scoped public packages
npm publish --access public

# For private packages
npm publish --access restricted

Practice: Package Configuration

Here's a complete package.json for a publishable package:

Version Management

Semantic Versioning

# Bump patch (1.0.0 → 1.0.1)
npm version patch

# Bump minor (1.0.0 → 1.1.0)
npm version minor

# Bump major (1.0.0 → 2.0.0)
npm version major

# Set specific version
npm version 2.0.0-beta.1

These commands:

1. Update package.json
2. Create a git commit
3. Create a git tag

Pre-release Versions

npm version prerelease --preid=beta
# 1.0.0 → 1.0.1-beta.0

npm version prerelease --preid=beta
# 1.0.1-beta.0 → 1.0.1-beta.1

Distribution Tags

# Publish with a tag
npm publish --tag beta

# Install specific tag
npm install my-package@beta

# List tags
npm dist-tag ls my-package

# Add tag to existing version
npm dist-tag add my-package@1.2.3 latest

Common tags:

• latest - Default, stable release
• beta - Beta releases
• next - Preview releases
• canary - Experimental builds

Unpublishing

# Unpublish specific version (within 72 hours)
npm unpublish my-package@1.0.0

# Unpublish entire package
npm unpublish my-package --force

Warning: Unpublishing can break other projects. Consider deprecating instead:

npm deprecate my-package@1.0.0 "Use version 2.0.0 instead"

Automating Releases

Use tools like semantic-release:

npm install -D semantic-release

{
  "scripts": {
    "release": "semantic-release"
  }
}

This automates:

• Version bumping based on commits
• Changelog generation
• npm publishing
• Git tagging

Publishing Checklist

Before every publish:

1. Tests pass
2. Build succeeds
3. Version updated
4. Changelog updated
5. README current
6. npm pack --dry-run looks right

Best Practices

1. Use prepublishOnly Script

{
  "scripts": {
    "prepublishOnly": "npm test && npm run build"
  }
}

2. Include Type Definitions

{
  "types": "dist/index.d.ts"
}

3. Support Multiple Module Systems

{
  "main": "dist/index.cjs",
  "module": "dist/index.mjs",
  "exports": {
    ".": {
      "require": "./dist/index.cjs",
      "import": "./dist/index.mjs"
    }
  }
}

4. Test Your Package

npm pack
cd /tmp
npm init -y
npm install /path/to/package-1.0.0.tgz
node -e "require('my-package')"

Key Takeaways

1. npm login before publishing
2. files field controls what's included
3. npm version manages versions
4. npm pack previews the package
5. prepublishOnly ensures quality

What's Next?

Let's learn about npm security and how to keep your dependencies safe.