Configure an NPM registry
Use the npm config set registry <url> command to set the NPM registry for your system.
This command will create an .npmrc file with the custom registry url in the current user's home directory.
The url should be a fully-qualified url to a packagecloud repository and must include the trailing npm/.
For example, to set the NPM registry to example-user's repository named example-repo,
you would run the following command:
npm config set registry https://packagecloud.io/example-user/example-repo/npm/
Follow the directions in the next sections to set up read-only access or
read and write access to the repository.
Read only access to NPM repositories
Public NPM repositories
If the repostory is a public repository, your system will have read access to the repository after running npm config set registry <url>
as described in the previous section.
You can install packages by simply running npm install [packagename].
Private NPM repositories
To configure read only access to a private NPM registry, use the repository installation scripts which can be found
in the Installation section on a repository page.
Alternatively, you can create a read token and and set the _authToken manually by editing the .npmrc file
in your user's home directory.
.npmrc file:
always-auth=true
registry=https://packagecloud.io/example-user/example-repo/npm/
//packagecloud.io/example-user/example-repo/npm/:_authToken=f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0
Note: The registry url must end in /npm/
The _authToken must be a valid read token generated from a repository master token. Learn more about read tokens in these docs.
The always-auth field is required when using Yarn with a private repository.
Read and write access to NPM repositories
You should only follow these instructions on systems and environments where you need write access to your repository. If you just need
to run npm install to install packages, you should follow the read only access guide above.
npm login
After you have set your repository URL by following the guide above, you
are ready to use npm login to give yourself write access to the repository.
Start by using the npm login command. Running this command
will modify the .npmrc file in your home directory to include an authentication token that has write access.
When running the npm login command, you will be prompted for a username, password, and email address.
Use your packagecloud account name, your packagecloud account password, and packagecloud account email address, respectively.
For example, if your packagecloud username is example-user and the email address registered to your account is
example-user@company.com, you would run npm login and respond like this:
~/Projects/example-project $ npm login
Username: example-user
Password: **************
Email: (this IS public) example-user@company.com
Logged in as example-user on https://packagecloud.io/example-user/example-repo/npm/.
npm publish
After you have followed the npm login section above, you
are ready to use npm publish.
Use the npm cli to publish packages to your packagecloud registry.
Run npm publish <tarball> or npm publish
from inside a project root containing a package.json to publish
packages to a configured registry.
You can also use the packagecloud CLI, API, or web
interface to upload packages to the NPM registry.
Scoped packages
Scoped packages are supported on packagecloud. Install scoped packages by including the scope in the package name.
npm install @example/package
Publishing scoped packages is also supported. Use the npm publish command, packagecloud CLI, or web UI to upload packages.
Ensure the scope is included in the package name field inside the package.json.
npm publish example-package-v0.1.0.tgz
Remove / unpublish packages from the registry
To remove packages from your packagecloud registry, you can use the packagecloud CLI or the API directly to delete the package.
CLI Example:
package_cloud yank example-user/example-repository/node example-1.0.tgz
To remove scoped packages from your packagecloud registry, you pass the scope to the CLI, like so:
package_cloud yank example-user/example-repository/node @myuser/example-1.0.tgz
You can also delete packages from the web UI by visiting the repository page, selecting the package you want to delete, and choosing delete from the options presented. Deleting the package will trigger a reindex of the registry metadata.
Transparent auto-proxying
When you install a package using npm install, the npm program will automatically
attempt to install any dependencies required by the package. If those dependencies are not found in your
packagecloud repository, packagecloud will automatically forward requests for those missing dependencies to the official
NPM public registry.
This is the default behavior and is recommended for most users.
If you do not want to rely on the official NPM public registry at all, you can disable the automatic forwarding
of requests. However, once this behavior is disabled, you will need to upload your packages and all
required dependencies to your packagecloud repository. To disable automatic proxying to the
official NPM public registry for missing dependencies, visit the settings page for the repository and
uncheck the "Enable proxying from the official NPM registry" checkbox.
If you decide to disable this behavior, you will have to upload every
dependency for every package you upload. npm install commands
will fail if any dependencies are missing from your packagecloud repository
because npm install will no longer be able to rely on the
official NPM public registry.
Using Yarn
Once a system is configured to use a packagecloud repository as an NPM registry, either by following the manual installation instructions, or by using the repository install scripts provided by packagecloud, it can install packages via Yarn by using yarn add <packagename>. No other configuration is necessary.
yarn add packagename@0.1.0
NPM dist tags
NPM supports a useful feature called distribution tags (or dist tags) for short. You can learn about
dist tags by reading the NPM documentation.
Please read the important notes about dist tags in the sections that follow. The behavior of dist tags with
package publish, promote, and delete may not be what you expect!
In short, NPM dist tags allow NPM package owners to associate arbitrary strings with NPM package versions.
All packages have at least one dist tag: the "latest" dist tag. The "latest" dist tag is automatically
set to the most recently uploaded version of a package. When you run npm install package, your npm
command line client automatically installs the version tagged with "latest".
You can create arbitrary dist tags (for example: alpha, beta, testing, stable, etc) that map to
particular versions of a package. A user can then use that dist tag to install the version of a package mapped
to that tag.
For example: you may decide that version 2.0 of example-package is the current beta version, so you create
a dist tag mapping "beta" to version 2.0. Any user who wants to install the beta, can simply run
npm install example-package@beta.
The NPM API for adding, removing, and listing dist tags
is fully supported by packagecloud. This means you can run commands like: npm dist-tag ls package-name or
npm dist-tag add package-name@2.0 beta to list or add dist tags, respectively.
Publishing a package and distribution tags (dist tags)
In order to maintain API compatibility with the official NPM registry and its API you should be be aware that
when uploading a Node.js package with the:
- Web-based graphical upload dialog, the package uploaded will be marked as
the latest version regardless of its version string.
- package_cloud command
line client, the package uploaded will be marked as the latest version regardless of its version string.
npm publish command without specifying a distribution tag,
the newly published package will be marked as the latest version regardless of its version string.npm publish command and also specifying a distribution tag
using the --tag option, the newly published package will be marked with the specified dist tag. The "latest"
distribution tag will remain unchanged and will be set to whichever version it was set to (if any).
You can add, remove, or list dist tags using the
npm dist-tags command
to modify the dist tags, manually.
Node package promotion and distribution tags (dist tags)
When you promote a package, the package is removed from the source repository and exists
only in the destination repository at the completion of the command.
When a Node.js package is promoted, the follow things occur:
- All distribution tags associated with that package are deleted.
- The remaining versions of the package in the original repository (where the package was moved from) will be sorted
according to the version. The most recent version string is marked as the latest (even if it already has another dist tag).
- Once the package reaches the destination repository, it will be marked as latest if (and only if) no other versions of the same package
exist at the destination. If other versions exist, the version that was just moved has no dist tag associated with it, even if the
semantic version is the latest.
This is done to mimic the official NPM repository as closely as possible. You can use the
npm dist-tags command
to create, remove, or adjust any dist tags you need after promoting a package.
Node package deletion and distribution tags (dist tags)
When you delete (or yank) a Node.js package the version strings of all remaining
versions for that package are sorted and the most recent version is marked as "latest" even if there is already another dist tag associated
with that version. This is done to maintain API compatibility with the official NPM registry and its API.