CLI Publish

The packship publish command is used to publish your package to the npm registry. This guide explains how to use the command and its various options.

Basic Usage

To publish your package to npm, simply run:

packship publish

This command will:

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

Command Options

The publish command supports several options to customize the publishing process:

--tag [tag]

Specify a tag for the published package. By default, packages are published with the latest tag.

# Publish with the beta tag
packship publish --tag beta

# Publish with the next tag
packship 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

--access [public|restricted]

Specify the access level for scoped packages. By default, scoped packages are published as restricted (private).

# Publish a scoped package as public
packship publish --access public

--dry-run

Perform a dry run to see what would happen without actually publishing the package.

packship publish --dry-run

--no-build

Skip the build step before publishing.

packship publish --no-build

--no-test

Skip running tests before publishing.

packship publish --no-test

Publishing Workflow

The packship publish command follows a specific workflow:

1. Pre-publish Checks

Before publishing, PackShip performs several checks:

• Verifies that you're logged in to npm
• Checks if the package name is available (for new packages)
• Validates the package.json file
• Ensures that the version hasn't already been published

2. Building

Unless --no-build is specified, PackShip will build your package:

npm run build

3. Testing

Unless --no-test is specified, PackShip will run your tests:

npm test

4. Publishing

Finally, PackShip publishes your package to npm:

npm publish [--tag <tag>] [--access <public|restricted>]

Versioning

Before publishing, you should update your package version. PackShip follows semantic versioning (SemVer):

• 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 Examples

Publishing a New Package

# Initialize a new package
packship init

# Make your changes
# ...

# Build and publish
packship publish

Publishing an Update

# Update the version
npm version patch

# Build and publish
packship publish

Publishing a Beta Version

# Update the version with a beta tag
npm version prerelease --preid=beta

# Build and publish with the beta tag
packship publish --tag beta

Publishing a Scoped Package

# For a public scoped package
packship publish --access public

# For a private scoped package (default)
packship publish

Troubleshooting

Authentication Issues

If you encounter authentication issues:

• Ensure you're logged in with npm login
• Check your npm token if you're using one
• Verify that you have the necessary permissions to publish

Version Conflicts

If you get an error about the version already existing:

• Update your package version with npm version
• Check the npm registry to see what versions are already published

Build Failures

If your build fails during publishing:

• Run npm run build separately to debug the issue
• Check your build configuration
• Ensure all dependencies are installed

Best Practices

• Always test before publishing: Ensure your package works as expected
• Use semantic versioning: Follow SemVer to communicate changes to users
• Include comprehensive documentation: Make it easy for users to understand your package
• Use a .npmignore file: Exclude unnecessary files from your package
• Set up CI/CD for publishing: Automate the publishing process