npm packages

Overview

npm packages let you sell front-end libraries, components and tooling the same way you sell Composer packages. Licenses, release channels, coupons, bundles and the customer portal all work the same way.

The difference is where releases come from. Composer packages are synced from GitHub releases. npm packages are published straight to Privato's private npm registry with npm publish, from your machine or from CI.

Creating an npm package

When creating a package, choose npm as the package type and enter the package's name.

npm package names must be scoped, for example @acme/ui, and must match the name field in your package.json. Customers route that scope to Privato, so the rest of their dependencies keep installing from the public npm registry.

Publishing

Open your package in Privato and click Generate publish token on the summary page. The token is only shown once, so store it somewhere safe, e.g. as a PRIVATO_NPM_TOKEN secret in CI. Each package has its own token, and it can only publish that package. Regenerating the token stops the old one working immediately.

Point publishing at Privato by adding publishConfig to your package.json. This also stops npm publish from accidentally sending your code to the public npm registry:

{
    "name": "@acme/ui",
    "version": "1.0.0",
    "publishConfig": {
        "registry": "https://acme.privato.pub/npm/"
    }
}

Then authenticate in the package's .npmrc, reading the token from an environment variable so it's never committed:

//acme.privato.pub/npm/:_authToken=${PRIVATO_NPM_TOKEN}

Publish a new version:

npm version patch
npm publish

Your package page in Privato shows these snippets with your own domain filled in.

Versions and tags

Every version you publish becomes a release in Privato. Published versions can't be overwritten, so bump the version before publishing again.

Versions are checked against your release channels the same way as Composer releases. The latest tag always points at the newest stable version a customer's license gives them access to. Other tags such as beta or next (npm publish --tag beta) are available to customers whose license includes that version.

Installing

Customers configure the registry and their credentials in their project's .npmrc. The installation tab in the customer portal has these lines ready to copy, with the customer's encoded credentials filled in:

@acme:registry=https://acme.privato.pub/npm/
//acme.privato.pub/npm/:_auth=<BASE64_EMAIL_AND_LICENSE_KEY>

The _auth value is the customer's email address and license key, joined with a colon and base64-encoded. These are the same credentials customers use for Composer packages.

Then install the package as normal:

npm install @acme/ui

pnpm reads the same .npmrc settings.

Connecting a GitHub repository

You can optionally connect an npm package to a private GitHub repository, either when creating the package or from the Source section of the package's Settings tab. Your team needs to be connected to GitHub first.

A connected repository enables:

• Hosted documentation, read from the repository's docs/ directory.
• Repository invitations, so customers who add their GitHub username in the customer portal are invited to the repository as collaborators.
• License agreements, so customers have to accept the LICENSE file from your repository at checkout.

Releases still only come from npm publish. Privato doesn't create releases from your GitHub releases, and there's no Sync releases action for npm packages.

Removing the repository turns hosted documentation, repository invitations and license agreements off again.

Limitations

• Only npm publish is supported. npm unpublish, npm deprecate and npm dist-tag aren't supported yet. You can delete a release from the package's releases tab in Privato.
• Hosted documentation, repository invitations and license agreements need a connected GitHub repository.
• Hosted documentation syncs when you publish a release on the connected GitHub repository, not when you run npm publish. You can also refresh it from the package's Settings tab.