GCP Task Runner (Remote Cache)
Relevant source files
The following files were used as context for generating this wiki page:
GCP Task Runner is an Nx plugin that enables Google Cloud Storage (GCS) as a remote cache provider for Nx workspaces. It acts as a drop-in replacement for the default Nx cache, allowing teams to share build artifacts and task results across different machines and CI environments.
Sources: packages/gcp-task-runner/README.md:1-12, README.md:32-34
Core Functionality
The task runner integrates with the Nx caching infrastructure to store and retrieve task outputs. When a task executes, the runner checks the configured GCS bucket for an existing entry matching the task's hash. If found, the runner downloads and restores the cached artifacts. If not found, the task executes locally, and the runner subsequently tars the output files and uploads them to GCS for future use.
Sources: packages/gcp-task-runner/README.md:10-12, packages/gcp-task-runner/CHANGELOG.md:113-115
Implementation Details
The package is built as a library using the @nx/js:tsc executor. It relies on the @google-cloud/storage library to interact with GCP services. The cache output paths include the task hash to ensure uniqueness and prevent collisions.
Sources: packages/gcp-task-runner/project.json:7-12, packages/gcp-task-runner/package.json:6-8, packages/gcp-task-runner/CHANGELOG.md:76-78
Cache Flow
The following diagram illustrates the interaction between the Nx CLI, the GCP Task Runner, and Google Cloud Storage.
The diagram shows the decision logic for cache hits and misses, including the requirement to tar files before uploading.
Sources: packages/gcp-task-runner/README.md:25-30, packages/gcp-task-runner/CHANGELOG.md:113-115
Setup and Configuration
Installation
The plugin is installed by aliasing it to the @nx/gcs-cache scope. This allows Nx to recognize it as a valid cache implementation.
npm install -D @nx/gcs-cache@npm:@nx-extend/gcp-task-runner
Sources: packages/gcp-task-runner/README.md:19-21, README.md:32-34
Configuration Options
Configuration is managed within the nx.json file. The runner requires a specific bucket name to be defined.
| Name | Type | Description |
|---|---|---|
bucket | string | The name of the Google Cloud Storage bucket used for storing cache artifacts. |
Sources: packages/gcp-task-runner/README.md:28-44
Authentication
The runner uses the official @google-cloud/storage client, which supports standard Google Cloud authentication methods. The most common method is using the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a service account key file.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
Sources: packages/gcp-task-runner/README.md:33-40
Project Integration
The task runner is managed as a standard Nx project within the packages/gcp-task-runner directory. It includes targets for building, linting, testing, and publishing.
Project Targets
| Target | Executor | Description |
|---|---|---|
build | @nx/js:tsc | Compiles the TypeScript source code to the dist directory. |
lint | @nx/eslint:lint | Validates code quality using ESLint. |
test | @nx/jest:jest | Runs unit tests using Jest. |
publish | nx:run-commands | Publishes the built package to the npm registry. |
Sources: packages/gcp-task-runner/project.json:7-69
Summary
GCP Task Runner provides a scalable remote caching solution for Nx workspaces by leveraging Google Cloud Storage. By persisting task outputs in a centralized bucket, it reduces redundant computation and accelerates CI/CD pipelines across development teams.
Sources: packages/gcp-task-runner/README.md:1-12, README.md:5-7