JavaScript

Buildkite Packages provides registry support for JavaScript-based (Node.js npm) packages.

Once your JavaScript registry has been created, you can publish/upload packages (generated from your application's build) to this registry by configuring your ~/.npmrc and application's relevant package.json files with the command/code snippets presented on your JavaScript registry's details page.

To view and copy the required command/code snippet for your ~/.npmrc and package.json configurations:

  1. Select Packages in the global navigation to access the Registries page.
  2. Select your JavaScript registry on this page.
  3. Select Publish a Nodejs Package and in the resulting dialog, use the copy icon at the top-right of the relevant code box to copy its snippet and paste it into your command line tool or the appropriate file.

These file configurations contain the following:

  • ~/.npmrc: the URL for your specific JavaScript registry in Buildkite and API write token (generated by Buildkite Packages) required to publish the package to this registry
  • package.json: the URL for your specific JavaScript registry in Buildkite.

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 submitting to update your ~/.npmrc file:

    npm set "//buildkitepackages.com/{org.slug}/{registry.name}/npm/:_authToken" registry-write-token

    where:

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

    • {registry.name} is the name of your JavaScript registry.

    • registry-write-token is the Buildkite Packages-generated API token required to publish/upload packages to your JavaScript registry.

    Note:

    • If your .npmrc file doesn't exist, this command automatically creates it for you.
    • This step only needs to be conducted 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://buildkitepackages.com/{org.slug}/{registry.name}/npm/"}
}

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

  3. Publish your package:

    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 within the Packages section. The package's details page is displayed.

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.

  • Last 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 download a package:

  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 install a package:

  1. Access the package's details.
  2. Ensure the Installation > Installation instructions section is displayed.
  3. Copy the command in the code snippet, paste it into your terminal, and submit it.

This code snippet is based on this format:

npm install nodejs-package-name@version.number \
  --registry https://{registry.read.token}@buildkitepackages.com/{org.slug}/{registry.name}/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)

  • {registry.read.token} is the Buildkite Packages-generated API token required to download packages from your JavaScript registry. This URL component, along with the following @ are not required for registries that are publicly accessible.

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