Building Node.js applications

This page describes how to configure Cloud Build to build and test your Node.js applications. If you're new to Cloud Build, read the quickstarts and the build configuration overview first.

Cloud Build enables you to use any publicly available container image to execute your tasks. The public node image from Docker Hub comes preinstalled with npm and yarn tools. You can configure Cloud Build to build your Node.js project with these tools.

Before you begin

The instructions on this page assume that you are familiar with Node.js. In addition:

• Have your Node.js project handy, including package.json and test.js files.
• Make sure your package.json file includes a start script and a test script.
• To run the gcloud commands in this page, install the gcloud command-line tool.

Building with npm or yarn

To execute your tasks in the node image from Docker Hub, specify the image URL in the name field in the Cloud Build config file. Cloud Build starts the container specified in the name field using the image's default entrypoint. To override the default entrypoint and define how the build step should be run when it is invoked, add an entrypoint field in your build step. The node image in Docker Hub comes preinstalled with npm and yarn tools. Specify the tools in the entrypoint field to invoke them as the entrypoint of your build step.

In the following example build config file:

• The name field specifies that the node image from Docker Hub is used by Cloud Build to execute your task. When you're specifying the node image, you can either omit the node version to default to :latest, or specify a node version to use a specific version. For example, name: node will use the latest version of node, and name: node:12 will use node:12.

• The entrypoint field specifies that the npm or the yarn tool is used when the node image is invoked.

npm

  steps:
  - name: node
    entrypoint: npm

yarn

  steps:
  - name: node
    entrypoint: yarn

Configuring Node.js builds

1. In your project root directory, create a config file named cloudbuild.yaml.

2. Install dependencies: Before you can build your application, you must ensure that all of your project's dependencies are installed from npm or yarn. You can install dependencies using the install command within the npm or yarn build step. The args field of a build step takes a list of arguments and passes them to the image referenced by the name field. In your build config file, add install to the args field to invoke the install command:

   npm

   steps:
   - name: node
     entrypoint: npm
     args: ['install']
   

   yarn

   steps:
   - name: node
     entrypoint: yarn
     args: ['install']
   

3. Add tests: If you've defined a test script in your package.json, you can configure Cloud Build to run the script by adding test to the args field:

   npm

   steps:
   - name: node
     entrypoint: npm
     args: ['install']
   - name: node
     entrypoint: npm
     args: ['test']
   

   yarn

   steps:
   - name: node
     entrypoint: yarn
     args: ['install']
   - name: node
     entrypoint: yarn
     args: ['test']
   

4. Run custom commands: If your package.json contains any custom commands, you can configure Cloud Build to run that command. In the args field, add run as the first argument followed by the name of the custom command. The following build config file has arguments to run a custom command called build:

   npm

   steps:
   - name: node
     entrypoint: npm
     args: ['install']
   - name: node
     entrypoint: npm
     args: ['test']
   - name: node
     entrypoint: npm
     args: ['run', 'build']
   

   yarn

   steps:
   - name: node
     entrypoint: yarn
     args: ['install']
   - name: node
     entrypoint: yarn
     args: ['test']
   - name: node
     entrypoint: yarn
     args: ['run', 'build']
   

5. Start the build using the build config file:

   gcloud builds submit --config [CONFIG_FILE_PATH] [SOURCE_DIRECTORY]
   

   Where:

   • [CONFIG_FILE_PATH] is the path to the build config file.
   • [SOURCE_DIRECTORY] is the path or URL to the source code.

   If you don't specify a [CONFIG_FILE_PATH] and [SOURCE_DIRECTORY] in the gcloud builds submit command, Cloud Build assumes that the config file and the source code are in the current working directory.

Running tests on multiple node versions

Sometimes it is necessary to ensure that your project works across multiple versions of node. You can create and configure Cloud Build triggers such that:

• In your build config file, specify the node version as a substitution variable.
• Create one trigger for each version of node against which you want to build your application.
• In each of the trigger settings, use the substitution variable value field to indicate the version of the node for that trigger.

The following steps explain how to specify the node version using trigger-specific substitution variables:

1. In your repository root, add a build config file, which specifies the node version as a substitution variable. In the following example build config file, $_NODE_VERSION is a user-defined substitution variable:

   npm

   steps:
   - name: node:$_NODE_VERSION
     entrypoint: npm
     args: ['install']
   - name: node:$_NODE_VERSION
     entrypoint: npm
     args: ['test']
   

   yarn

   steps:
   - name: node:$_NODE_VERSION
     entrypoint: yarn
     args: ['install']
   - name: node:$_NODE_VERSION
     entrypoint: yarn
     args: ['test']
   

2. For each version of node you want to build against, create a build trigger using the following steps:

   1. Open the Triggers page in the Google Cloud Console:

      Open Triggers page

   2. Select your project from the project selector drop-down menu at the top of the page.

   3. Click Open.

   4. Click Create trigger.

      On the Create trigger page, enter the following settings:

      1. Enter a name for your trigger.

      2. Select the repository event to start your trigger.

      3. Select the repository that contains your source code and build config file.

      4. Specify the regex for the branch or tag name that will start your trigger.

      5. Configuration: Choose the build config file you created previously.

      6. Under Substitution variables, click Add variable.

         1. Under Variable, specify the node version variable you used in your build config file, and under Value specify the version of the node. For example, _NODE_VERSION and 12.

   5. Click Create to save your build trigger.

You can use these triggers to build your code on the version of node you specified in the trigger.

Code examples

Here are some sample repositories, each of which contains a sample Node.js application and a build config file to build and test that application:

• node-example-npm: A Node.js app and an example build config file to build the app with npm.
• node-example-yarn: A Node.js app and an example build config file to build the app with yarn.
• multiple-node-versions-example: An example with a build config file to build the app against multiple versions of node.

What's next

• Learn how to build container images.
• Learn how to build Go applications.
• Learn how to troubleshoot build errors.