Publishing

Publishing your package to npm makes it available for others to install and use. This guide explains how to prepare and publish your PackShip project to the npm registry.

Prerequisites

Before publishing your package, ensure you have:

An npm account (create one at npmjs.com)
Logged in to npm via the command line
A properly configured package.json file
Built your package

To publish packages, you need to be logged in to npm. Run the following command:

npm login

You'll be prompted to enter your username, password, and email address. If you have two-factor authentication enabled, you'll also need to provide an OTP (One-Time Password).

Preparing Your Package

Package.json Configuration

Ensure your package.json file is properly configured:

{
  "name": "my-package",          // Must be unique on npm
  "version": "1.0.0",            // Follow semantic versioning
  "description": "A description of my package",
  "main": "dist/index.js",       // Entry point for CommonJS
  "module": "dist/index.esm.js", // Entry point for ES modules
  "types": "dist/index.d.ts",    // TypeScript declarations
  "files": [                     // Files to include in the package
    "dist",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "packship build",
    "prepublishOnly": "npm run build"
  },
  "keywords": [                  // Help users find your package
    "react",
    "component",
    "ui"
  ],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-package.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-package/issues"
  },
  "homepage": "https://github.com/username/my-package#readme"
}

Building Your Package

Before publishing, build your package to generate the distribution files:

npm run build

This will create the compiled files in the dist/ directory.

README and Documentation

Ensure your package has a comprehensive README.md file that includes:

Package name and description
Installation instructions
Usage examples
API documentation
License information

License

Include a LICENSE file in your package. Common open-source licenses include MIT, Apache 2.0, and GPL.

Publishing Your Package

Using PackShip

PackShip provides a simplified publishing workflow. To publish your package:

packship publish

This command will:

Build your package
Run tests (if configured)
Publish to npm

Using npm

Alternatively, you can use the standard npm publish command:

npm publish

If you've set up the prepublishOnly script in your package.json, npm will automatically build your package before publishing.

Publishing a Scoped Package

If your package is scoped (e.g., @username/package-name), you need to specify that it's public:

npm publish --access public

Versioning

Follow semantic versioning (SemVer) for your package versions:

MAJOR version for incompatible API changes
MINOR version for new functionality in a backward-compatible manner
PATCH version for backward-compatible bug fixes

To update your package version:

# 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

Publishing Updates

To publish an update to your package:

Make your changes
Update the version number
Build the package
Publish to npm

# Update version
npm version patch

# Publish
packship publish

Unpublishing

npm has strict policies about unpublishing packages. You can unpublish a package within 72 hours of publishing:

npm unpublish my-package@1.0.0

After 72 hours, you can only unpublish a package in special circumstances. It's better to deprecate a package instead.

Deprecating a Package

To mark a package as deprecated:

npm deprecate my-package@1.0.0 "This version is deprecated, please use version 2.0.0 instead"

Publishing Best Practices

Test before publishing: Ensure your package works as expected before publishing.
Use a .npmignore file: Exclude unnecessary files from your package to reduce its size.
Include comprehensive documentation: Make it easy for users to understand and use your package.
Follow semantic versioning: Help users understand the impact of updates.
Use npm tags: Tag releases as latest, beta, etc.

Using npm Tags

You can publish a package with a specific tag:

# Publish as beta
npm publish --tag beta

# Publish as next
npm publish --tag next

Users can then install specific versions:

# Install latest stable version
npm install my-package

# Install beta version
npm install my-package@beta

Dependencies

Best Practices