Getting started

Before you start

To complete this tutorial, you'll need:

• A Buildkite account. If you don't have one already, create a 30-day free trial account.

• Git, to clone the Node.js package example.

• Node.js—macOS users can also install Node.js with Homebrew.

Create a source registry

First, create a new JavaScript source registry:

1. Select Package Registries in the global navigation to access the Registries page.
2. Select New registry > Source Registry.
3. On the New Registry page, enter the mandatory Name for your registry. For example, My JavaScript registry.
4. Enter an optional Description for the registry, which will appear under the name of the registry item on the Registries page. For example, This is an example of a JavaScript registry.
5. Select the required registry Ecosystem of JavaScript (npm).
6. If your Buildkite organization has the teams feature enabled, select the relevant Teams to be granted access to the new JavaScript registry.

7. Select Create Registry.

   The new JavaScript registry's details page is displayed. Selecting Package Registries in the global navigation opens the Registries page, where your new registry will be listed.

Clone the Node.js example package project

Then, clone the Node.js example package project:

1. Open a terminal or command prompt, and run the following command:

   git clone git@github.com:buildkite/nodejs-example-package.git
   

2. Change directory (cd) into the nodejs-example-package directory.

3. (Optional) Run the following npm command to test that the package executes successfully:

   npm run main
   

   The command output should display Hello world!.

Configure your Node.js environment and project

Next, configure your Node.js environment to publish Node.js packages to the JavaScript registry you created above:

1. Access your JavaScript registry's details page. To do this, select Package Registries in the global navigation > your npm package from the list.
2. Select Publish a JavaScript Package to open the dialog with code boxes.

3. Copy the npm command in the first code box and run it to configure your npm config settings file (.npmrc). This configuration allows you to publish packages to your JavaScript registry. The npm command has the following format:

   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 Package Registries or Pipelines in the global navigation of your organization in Buildkite.
   • {registry.slug} is the slug of your JavaScript source registry, which is the kebab-case version of this registry's name, and can be obtained after accessing Package Registries in the global navigation > your JavaScript source registry from the Registries page.
   • registry-write-token is your API access token used to publish/upload packages to your JavaScript source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any source registry your user account has access to within your Buildkite organization.

   Note:

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

4. Copy the publishConfig field and its value in the second code box and paste it to the end of your Node.js package's package.json file. Alternatively, select and copy the line of code beginning "publishConfig": .... For example:

   {
     "name": "nodejs-example-package",
     "version": "1.0.1",
     "description": "An example Node.js package for Buildkite Package Registries",
     "main": "index.js",
     "scripts": {
       "main": "node index.js"
     },
     "author": "A Person",
     "license": "MIT",
     "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, that is, "license": ... in this case.

Publish the package

Last, in the nodejs-example-package directory, publish your Node.js package to your JavaScript registry by running the following npm commands:

npm pack
npm publish

Your Node.js package is published to your Buildkite JavaScript registry in .tgz format.

Check the end result

To confirm that your Node.js package was successfully published to your Buildkite JavaScript registry:

1. View your JavaScript registry's details page, refreshing the page if necessary. To access this page, select Package Registries in the global navigation > your Node.js package from the list.

   The package name (for example, nodejs.example-package-1.0.1.tgz) should appear under Packages.

2. Click the package name to access its details, and note the following:

   • Instructions: this section of the Installation tab provides command line instructions for installing the package you just published.
   • Details tab: provides various checksum values for this published package.
   • About this version: obtained from the description field value of the package.json file.
   • Details, which lists the following (where any field values are also obtained from the package.json file):
     • The name of the package, obtained from the name field value.
     • The package version, obtained from the version field value.
     • The registry the package is located in.
     • The package's visibility (Private by default), based on its registry's visibility.
     • The distribution name/version (just node.js in this case).
     • The package's license, obtained from the license field value.
   • Download: select this to download the package locally.

To return to the your JavaScript registry details page (listing all packages published to this registry), select the registry's name at the top of the page.

Publish a new version

As an optional extra, try incrementing the version number in your packages.json file, re-publishing the package to your JavaScript registry, and checking the end result.

Your JavaScript registry's details page should show your new package with the incremented version number.

Next steps

That's it! You've created a new Buildkite registry, configured your Node.js environment and project to publish to your new JavaScript registry, and published a Node.js package to this registry. 🎉

Learn more about how to work with Buildkite Package Registries in Manage registries, and the difference between source and composite registries.