Skip to content
Nx Docs

Launch Template Examples

This page contains common configuration examples for launch templates. For the full reference of available fields, see the launch templates reference page.

Full example

Section titled “Full example”

This is an example of a launch template using all pre-built features:

./nx/workflows/agents.yaml
# Define common setup steps that can be reused across templates
common-js-init-steps: &common-js-init-steps
  # using a reusable step in an external GitHub repo,
  # this step is provided by Nx Cloud: https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps
  - name: Checkout
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
  - name: Restore Node Modules Cache
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
    # the cache step requires configuration via env vars
    # https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/cache#options
    inputs:
      # Include patches directories to ensure cache is busted when patches change
      # If you use a custom patches directory, add it to the key as well
      key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|patches/**|.yarn/patches/**'
      paths: |
        ~/.npm
        # or ~/.cache/yarn
        # or ~/.local/share/pnpm/store
      base-branch: 'main'
  - name: Restore Browser Binary Cache
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
    inputs:
      key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|"browsers"'
      paths: |
        '~/.cache/Cypress'
      base-branch: 'main'
  - name: Install Node Modules
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
  - name: Install Browsers (if needed)
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-browsers/main.yaml'
    # You can also run a custom script to configure various things on the agent machine
  - name: Run a custom script
    script: |
      git config --global user.email test@test.com
      git config --global user.name "Test Test"
  - name: Define Step Env Var
    # this env var will be available to all future steps using these 'common-init-steps' reusable steps
    # persist env vars between steps by writing to the $NX_CLOUD_ENV file
    script: |
      echo "MY_STEP_ENV=step-env-var" >> $NX_CLOUD_ENV


common-rust-init-steps: &common-rust-init-steps
  - name: Checkout
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'


  # add Rust-specific steps
  - name: Install Rust
    script: |
      curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
      source "$HOME/.cargo/env"
      rustup toolchain install stable
      # persist cargo bin into PATH
      echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV


launch-templates:
  # Custom template name, the name is referenced via --distribute-on="3 my-linux-medium-js"
  # You can define as many templates as you need, commonly used to make different sizes or toolchains depending on your workspace needs
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    # Define environment variables shared among all steps in this launch template
    env:
      MY_ENV_VAR: shared
    # list out steps to run on the agent before accepting tasks
    # the agent will need a copy of the source code and dependencies installed
    # note we are using yaml anchors to reduce duplication with the below launch-template (they have the same init-steps)
    init-steps: *common-js-init-steps


  # another template which does the same as above, but with a large resource class
  # You're not required to define a template for every resource class, only define what you need!
  my-linux-large-js:
    resource-class: 'docker_linux_amd64/large'
    image: 'ubuntu22.04-node20.19-v3'
    env:
      MY_ENV_VAR: shared
    # note we are using yaml anchors to reduce duplication with the above launch-template (they have the same init-steps)
    init-steps: *common-js-init-steps


  # template that installs rust
  my-linux-rust-large:
    resource-class: 'docker_linux_amd64/large'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps: *common-rust-init-steps

These templates can be used by passing the number of agents desired, and the template name via --distribute-on when starting your CI run.

Terminal window
nx-cloud start-ci-run --distribute-on="4 my-linux-medium-js"
Terminal window
nx-cloud start-ci-run --distribute-on="4 my-linux-large-js"
Terminal window
nx-cloud start-ci-run --distribute-on="4 my-linux-large-rust"

Pass environment variables

Section titled “Pass environment variables”

If you need to send environment variables to agents, you can use the --with-env-vars flag on the nx-cloud start-ci-run command. You can pass a specific list of environment variables like this:

Terminal window
nx-cloud start-ci-run --distribute-on="8 linux-medium-js" --with-env-vars="VAR1,VAR2"

Pass values between steps

Section titled “Pass values between steps”

If you need to pass a value from one step to another step, such as assigning the value to an existing or new environment variable. You can write to the NX_CLOUD_ENV environment file.

Commonly used for redefining the PATH or setting options for tooling.

./nx/workflows/agents.yaml
launch-templates:
  my-template-name:
    init-steps:
      - name: Set PATH
        script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV
      - name: Check PATH
        script: |
          # now contains $HOME/.cargo/bin
          echo $PATH
          # can invoke cargo directly because it's in the PATH now.
          cargo --version

Private npm registry

Section titled “Private npm registry”

If your project consumes packages from a private registry, you'll have to set up an authentication step in a custom launch template and authenticate like you normally would, usually this is via a .npmrc or .yarnrc file. You can pass the auth token from your main agent, so it's available to the agent machines.

.nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Auth to Registry
        script: |
          # we recommend add to the 'user' level npmrc file
          # create .npmrc with @myorg scoped packages pointing to GH npm registry
          # or yarn config set -l user if you use yarn
          npm config set -L user "@myorg:registry" "https://npm.pkg.github.com"
          npm config set -L user "//npm.pkg.github.com/:_authToken" "${SOME_AUTH_TOKEN}"
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'

Pass SOME_AUTH_TOKEN via --with-env-vars

Terminal window
# this assumes SOME_AUTH_TOKEN is already defined on the main agent
nx-cloud start-ci-run --distribute-on="5 my-linux-medium-js" --with-env-vars="SOME_AUTH_TOKEN"

Custom node version

Section titled “Custom node version”

Nx Agents come with node LTS installed. If you want to use a different version, you can add a step to install the desired node version.

You can use mise to manage node versions alongside other toolchains.

.nx/workflows/agents.yaml
launch-templates:
  node-21:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install mise
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
        inputs:
          # you can also define a mise.toml in your repo instead of inline tools
          tools: |
            node=21
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'

Specific package manager version

Section titled “Specific package manager version”

Nx Agents have corepack enabled by default, allowing you to define the yarn or pnpm version via the package.json.

package.json
{
  "packageManager": "yarn@4.1.1"
}

Installing packages

Section titled “Installing packages”

You can use apt to install popular linux packages. This is helpful in streamlining setting up various toolchains needed for your workspace.

For example, you can install the GitHub CLI on the agents if needed.

./nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps:
      - name: Install Extras
        script: |
          sudo apt install gh unzip zip -y

Install tools with mise

Section titled “Install tools with mise”

mise is a polyglot version manager that can install and manage multiple tools and runtimes (node, Rust, Python, Go, and more) in a single step. Nx Cloud provides a pre-built step to install mise and configure tools on your agents.

If your repo already has a mise.toml file, mise automatically installs the tools defined there.

.nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install mise
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'

AWS CLI

Section titled “AWS CLI”

First, define the environment variables on your main agent, where you call nx-cloud start-ci-run. Pass the same environment variables to your agents via the --with-env-vars flag.

Minimally the AWS_REGION (or AWS_DEFAULT_REGION), AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY environment variables are required.

Using the pre-built step simplifies and provides debugging checks to make sure the AWS CLI is properly authenticated to AWS before continuing. The step is recommended for most use cases.

./nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    init-steps:
      - name: Install AWS CLI
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-aws-cli/main.yaml'
        # no additional inputs required, as all configuration is via environment variables via --with-env-vars

Dynamic changesets

Section titled “Dynamic changesets”

NxCloud can calculate how big your pull request is based on how many projects in your workspace it affects. You can then configure Nx Agents to dynamically use a different number of agents based on your changeset size.

Here we define a small, medium and large distribution strategy:

.nx/workflows/dynamic-changesets.yaml
distribute-on:
  small-changeset: 3 linux-medium-js
  medium-changeset: 8 linux-medium-js
  large-changeset: 12 linux-medium-js

Then you can pass the path to the file to the --distribute-on parameter.

Terminal window
nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml"

Debugging

Section titled “Debugging”

You can add steps to your template which print information about your workspace, toolchains, or any other needs. Below are some common steps people use for debugging such as running nx commands, printing file contents and/or listing directory contents.

.nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    env:
      # enable verbose logging for all steps
      NX_VERBOSE_LOGGING: true
    init-steps:
      - name: 'Debug: Print Nx Report'
        script: |
          nx report
      - name: 'Debug: List Directory Contents'
        script: |
          echo $HOME
          ls -la $HOME
          output_dir=$HOME/dist
          # if output directory exists list it's contents
          if [ -d output_dir ]; then
            ls -la $output_dir
          else
            echo "$output_dir does not exist"
          fi
      - name: 'Debug: Show File Contents'
        script: |
          cat $HOME/.profile
      - name: 'Debug: Check For Checkout Files'
        script: |
          git diff
      - name: 'Debug: Print Versions'
        script: |
          # note if you use yarn and try to run pnpm, corepack might throw an error at you
          # saying you're using the wrong package manager, in that case just remove the usage of pnpm
          echo "Versions:"
          echo "Node: $(node -v)"
          echo "NPM: $(npm -v)"
          echo "Yarn: $(yarn -v)"
          echo "PNPM: $(pnpm -v)"
          echo "Golang: $(go version)"
          echo "Java: $(javac --version)"
          # add any other toolchain you want
      - name: 'Debug: Print env'
        script: |
          # !!! DO NOT RUN THIS IF YOU HAVE PASSWORD/ACCESS TOKENS IN YOUR ENV VARS !!!
          # this will print your env as plain text values to the terminal
          env
          # This is a safer approach to prevent leaking tokens/passwords
          echo "SOME_VALUE: $SOME_VALUE"

Nx workspace in a subdirectory

Section titled “Nx workspace in a subdirectory”

If your Nx workspace is in a subdirectory of your repository, set NX_WORKING_DIRECTORY in your launch template:

launch-templates:
  my-template:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node20.19-v3'
    env:
      NX_WORKING_DIRECTORY: './client'
    init-steps:
      # ...

The install-node-modules step automatically respects this variable (but can be overridden at the step level if your lockfile is hosted at the root). For other steps, set the working directory manually.