Overview of the Nx GCS Cache Plugin

The @nx/gcs-cache plugin enables you to self-host your remote cache on Google Cloud Storage.

Set Up @nx/gcs-cache

1. Install the Package

Run the following command:

nx add @nx/gcs-cache

This will add the @nx/gcs-cache NPM package and automatically configure it for your workspace. As part of this process, you'll be guided to generate a new activation key. This is a fully automated process to register your plugin.

The key will be saved in your repository (.nx/key/key.ini) and should be committed so that every developer has access to it. If your repository is public (or in CI), you can also use an environment variable:

NX_KEY=YOUR_ACTIVATION_KEY

Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server. Learn more.

2. Authenticate with Google Cloud

There are several ways to authenticate with Google Cloud Storage, but the method recommended by Google is to use Workload Identity Federation, like this:

name: CI
...
permissions:
  id-token: write
  ...

jobs:
  main:
    env:
      NX_KEY: ${{ secrets.NX_KEY }}
    runs-on: ubuntu-latest
    steps:
        ...

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v2'
        with:
          token_format: 'access_token'
          workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
          service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

      - name: 'Set up Cloud SDK'
        uses: 'google-github-actions/setup-gcloud@v2'
        with:
          version: '>= 363.0.0'

        ...

      - run: pnpm exec nx affected -t lint test build

Note: Any authentication method that sets up the Application Default Credentials will enable the plugin to work.

3. Configure the Nx Cache to Use Google Cloud Storage

Finally, you need to configure your Nx cache in the nx.json file. The bucket that you specify needs to already exist - Nx doesn't create it for you.

{
  "gcs": {
    "bucket": "my-bucket"
  }
}

Property	Description
bucket	The name of the bucket to use

Migrating from Custom Tasks Runners

Many people who are interested in Nx Powerpack have previously used custom task runners. Nx offers a new and simpler extension API designed to meet the same use cases as the now-deprecated custom task runners.

To learn more about migrating from custom task runners, please refer to this detailed guide.

By default, Nx will try to write and read from the remote cache while running locally. This means that permissions must be set for users who are expected to access the remote cache.

Nx will only show warnings when the remote cache is not writable. You can disable these warnings by setting localMode to read-only or no-cache in the nx.json file.

{
  "gcs": {
    // ...
    "localMode": "read-only"
  }
}

The cache mode in CI can also be configured by setting ciMode to read-only or no-cache in the nx.json file. Or by setting NX_POWERPACK_CACHE_MODE to read-only or no-cache in the CI environment.

{
  "gcs": {
    // ...
    "ciMode": "read-only"
  }
}