How to Publish an npm Package

Publish a Node.js package to your organization’s npm registry using the npm publish command.

Prerequisites

An organization on pckgs.io with an npm registry. See Create an Organization.
A pckgs.io access token with write access to your organization. See Create an Access Token.
Authentication configured. See npm Package Registry Authentication.

Configure `package.json`

Your package name must be scoped, an unscoped name is rejected by the registry. Point publishConfig.registry at your organization’s registry so the package can never be published to the wrong place by accident:

{
  "name": "@<YOUR_SCOPE>/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://npm.pckgs.io/<YOUR_ORG_SLUG>/"
  }
}

Without publishConfig, npm publishes scoped packages to whatever registry the scope is mapped to in your .npmrc.

Publish the Package

Run the following command from your package root:

npm publish

npm packs your files into a tarball, uploads it to pckgs.io using your stored access token.

Visibility

Scoped packages default to --access restricted which uploads the package as private. If you want to upload a public package you can use --access public with your npm publish command as

npm publish --access public

Once package is uploaded to pckgs.io you can manage it’s visibility from package’s settings page as long as you have manage permission for that specific package.

Preview Before Publishing

To see exactly which files would be included without uploading anything:

npm publish --dry-run

Publishing a New Version

A version that already exists cannot be overwritten. Bump it first:

npm version patch
npm publish

Publishing from CI

Write the scope mapping and token into .npmrc at the start of the job, then publish:

echo "@<YOUR_SCOPE>:registry=https://npm.pckgs.io/<YOUR_ORG_SLUG>/" >> .npmrc
echo "//npm.pckgs.io/<YOUR_ORG_SLUG>/:_authToken=${PCKGS_TOKEN}" >> .npmrc
npm publish

Store PCKGS_TOKEN as an encrypted secret in your CI provider never in the repository.

Managing a Published Package

Dist Tags

Publish a prerelease under its own tag, then promote it when it’s ready:

npm publish --tag next
npm dist-tag add @<YOUR_SCOPE>/[email protected] latest
npm dist-tag ls @<YOUR_SCOPE>/my-package

Deprecate a Version

npm deprecate @<YOUR_SCOPE>/my-package@"<2.0.0" "Upgrade to v2 — v1 is no longer maintained"

Unpublish

Unpublish via npm unpublish is not supported since in pckgs.io access token can only read or write to a package. To unpublish a package you go to the package’s setting page and delete the package from there.

Need help? Contact us here or at [email protected].