JavaScript

Publish a package

The following steps describe the process above:

1. Copy the following npm command, paste it into your terminal, and modify as required before running to update your ~/.npmrc file:

   npm set //packages.buildkite.com/{org.slug}/{registry.slug}/npm/:_authToken registry-write-token
   

   where:

   • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Packages or Pipelines in the global navigation of your organization in Buildkite.
   • {registry.slug} is the slug of your JavaScript registry, which is the kebab-case version of your JavaScript registry name, and can be obtained after accessing Packages in the global navigation > your JavaScript registry from the Registries page.
   • registry-write-token is your API access token used to publish/upload packages to your JavaScript registry. Ensure this access token has the Write Packages REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.

   Note:

   • If your .npmrc file doesn't exist, this command automatically creates it for you.
   • This step only needs to be performed once for the life of your JavaScript registry.

2. Copy the following JSON code snippet (or the line of code beginning "publishConfig": ...), paste it into your Node.js project's package.json file, and modify as required:

   {
     ...,
     "publishConfig": {"registry": "https://packages.buildkite.com/{org.slug}/{registry.slug}/npm/"}
   }
   

   Note: Don't forget to add the separating comma between "publishConfig": ... and the previous field.

3. Build and publish your package:

   npm pack
   npm publish
   

Access a package's details

A JavaScript package's details can be accessed from this registry using the Packages section of your JavaScript registry page.

To access your JavaScript package's details page:

1. Select Packages in the global navigation to access the Registries page.
2. Select your JavaScript registry on this page.
3. On your JavaScript registry page, select the package to display its details page.

The package's details page provides the following information in the following sections:

• Installation (tab): the installation instructions.
• Contents (tab, where available): a list of directories and files contained within the package.
• Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
• About this version: a brief (metadata) description about the package.

• Details: details about:

  • the name of the package (typically the file name excluding any version details and extension).
  • the package version.
  • the registry the package is located in.
  • the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
  • the distribution name / version.
  • additional optional metadata contained within the package, such as a homepage, licenses, etc.

• Pushed: the date when the last package was uploaded to the registry.

• Total files: the total number of files (and directories) within the package.

• Dependencies: the number of dependency packages required by this package.

• Package size: the storage size (in bytes) of this package.

• Downloads: the number of times this package has been downloaded.

Downloading a package

A JavaScript package can be downloaded from the package's details page. To do this:

1. Access the package's details.
2. Select Download.

Installing a package

A JavaScript package can be installed using code snippet details provided on the package's details page. To do this:

1. Access the package's details.
2. Ensure the Installation > Instructions section is displayed.
3. If your registry is private and you haven't already performed this .npmrc configuration step, copy the npm set command from the Registry Configuration section, paste it into your terminal, and modify as required before running to update your ~/.npmrc file.
4. Copy the npm install command from the Package Installation section, paste it into your terminal, and modify as required before running it.

Registry Configuration

If your registry is private (that is, the default registry configuration), set your JavaScript registry's authentication details in the .npmrc file by running the npm set command:

npm set //packages.buildkite.com/{org.slug}/{registry.slug}/npm/:_authToken registry-read-token

where:

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Packages or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your JavaScript registry, which is the kebab-case version of your JavaScript registry name, and can be obtained after accessing Packages in the global navigation > your JavaScript registry from the Registries page.

• registry-read-token is your API access token or registry token used to download packages to your JavaScript registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

Package Installation

Install your JavaScript package by running the npm install command:

npm install nodejs-package-name@version.number \
  --registry https://packages.buildkite.com/{org.slug}/{registry.slug}/npm/

where:

• nodejs-package-name is the name of your Node.js package (that is, the name field value from its package.json file).

• version.number is the version of your Node.js package (that is, the version field value from its package.json file).

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Packages or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your JavaScript registry, which is the kebab-case version of your JavaScript registry name, and can be obtained after accessing Packages in the global navigation > your JavaScript registry from the Registries page.