{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "paths": {
      "@google-cloud/common": ["./source/core/common/src/index.ts"],
      "google-gax": ["./source/core/packages/gax/src/index.ts"],
      "gaxios": ["./source/core/packages/gaxios/src/index.ts"]
    }
  }
}

4. Set authentication environment variables:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# Or use Application Default Credentials (ADC) via:
gcloud auth application-default login

5. Set optional sample directory for jsdoc-region-tag if using the code sample loader:

export SAMPLES_DIRECTORY=/path/to/your/samples

6. Wire your Express/Fastify app to import from @google-cloud/* packages or the vendored paths above.

Public API

request (gaxios)

import { request, GaxiosOptions, GaxiosResponse } from 'gaxios';

async function request<T>(opts: GaxiosOptions): Promise<GaxiosResponse<T>>;

Use this as a drop-in fetch/axios replacement with built-in retry, Google Auth token injection, and consistent error handling. Prefer it over raw fetch when calling Google APIs or any JSON REST endpoint.

Service (common)

import { Service, ServiceConfig, ServiceOptions } from '@google-cloud/common';

class Service {
  constructor(config: ServiceConfig, options: ServiceOptions);
}

The base class all @google-cloud/* clients extend. Use it when building a custom GCP service wrapper that needs built-in authentication, request decoration, and retry logic without reimplementing boilerplate.

ServiceObject (common)

import {
  ServiceObject,
  ServiceObjectConfig,
  ServiceObjectParent,
  Metadata,
  MetadataCallback,
  DeleteCallback,
  ExistsCallback,
} from '@google-cloud/common';

class ServiceObject {
  constructor(config: ServiceObjectConfig);
  getMetadata(callback?: MetadataCallback): Promise<Metadata> | void;
  exists(callback?: ExistsCallback): Promise<boolean> | void;
  delete(callback?: DeleteCallback): Promise<void> | void;
}

Represents a remote GCP resource (bucket, topic, instance). Use it as the base for resource classes that expose exists(), delete(), and getMetadata() patterns consistent with the rest of the ecosystem.

GrpcClient (gax)

import { GrpcClient, GrpcClientOptions } from 'google-gax';

class GrpcClient {
  constructor(options: GrpcClientOptions);
}

Wraps @grpc/grpc-js with Google Auth credential injection. Use it when constructing a low-level gRPC stub for a GCP service that does not yet have a generated client package.

ApiError (common)

import { ApiError } from '@google-cloud/common';

class ApiError extends Error {
  code: number;
  errors: object[];
}

Structured error thrown by all @google-cloud/* HTTP clients. Inspect .code (HTTP status) and .errors array to implement conditional retry or user-facing error messages.

Working examples

Scenario - Make an authenticated HTTP request with gaxios

Perform a REST call to a Google API endpoint using Application Default Credentials managed externally, relying on gaxios for retries and response parsing.

import { request, GaxiosOptions } from 'gaxios';
import { GoogleAuth } from 'google-auth-library';

async function listBuckets(projectId: string): Promise<void> {
  const auth = new GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  });
  const client = await auth.getClient();
  const token = await client.getAccessToken();

  const opts: GaxiosOptions = {
    url: `https://storage.googleapis.com/storage/v1/b`,
    params: { project: projectId },
    headers: { Authorization: `Bearer ${token.token}` },
    responseType: 'json',
    retry: true,
  };

  const response = await request<{ items: { name: string }[] }>(opts);
  for (const bucket of response.data.items ?? []) {
    console.log(bucket.name);
  }
}

listBuckets('my-gcp-project');

Scenario - Build a custom GCP resource client using Service and ServiceObject

Extend the base classes from @google-cloud/common to create a minimal custom client without duplicating auth/retry logic.

import {
  Service,
  ServiceObject,
  ServiceConfig,
  ServiceOptions,
  ServiceObjectConfig,
} from '@google-cloud/common';

class MyService extends Service {
  constructor(options: ServiceOptions) {
    const config: ServiceConfig = {
      baseUrl: 'https://myapi.googleapis.com/v1',
      scopes: ['https://www.googleapis.com/auth/cloud-platform'],
      packageJson: require('./package.json'),
    };
    super(config, options);
  }

  widget(id: string): MyWidget {
    return new MyWidget({ parent: this, id, baseUrl: '/widgets' });
  }
}

class MyWidget extends ServiceObject {
  constructor(config: ServiceObjectConfig) {
    super(config);
  }
}

const svc = new MyService({ projectId: 'my-gcp-project' });
const w = svc.widget('widget-123');
w.getMetadata().then(meta => console.log(meta));

Scenario - Load code samples with jsdoc-region-tag

Parse annotated sample files to extract tagged code regions for documentation generation or testing.

// CommonJS context (jsdoc-region-tag is a CJS module)
const { loadSampleCache } = require('./source/core/dev-packages/jsdoc-region-tag/src/index.js');

process.env.SAMPLES_DIRECTORY = './samples';

const cache = loadSampleCache();
for (const [tag, snippet] of cache.entries()) {
  console.log(`=== ${tag} ===`);
  console.log(snippet);
}

File walkthrough

• .github/ - Contains GitHub Actions workflows (continuous, presubmit, conformance, system tests), issue templates, and bot configuration for auto-approve and release triggers.
• bin/ - Executable shell and MJS scripts for one-time operations: migrating split repos into the monorepo, generating README tables, and managing git history.
• ci/ - Cloud Build YAML configurations and shell scripts for running conditional, interdependent, and credentialed test pipelines on Google Cloud infrastructure.
• containers/ - Dockerfile and related definitions used by CI jobs that require custom runtime environments.
• core/ - The heart of the block: common (base service classes), gax (gRPC + REST transport, operation polling, page descriptors), gaxios (HTTP client), and dev utilities like pack-n-play and jsdoc-region-tag.
• docs/ - Source material for the public documentation site.
• handwritten/ - Manually maintained client code that supplements or overrides auto-generated output for specific services.
• packages/ - Auto-generated per-service packages, one directory per GCP API, published individually to npm as @google-cloud/*.
• libraries.json - Machine-readable catalog of all packages; used by scripts and CI to enumerate services.
• ignore.json - Exclusion list for linting and OwlBot copy operations.
• linkinator.config.json - Configuration for the link checker run in CI.

Common pitfalls and fixes

• GOOGLE_APPLICATION_CREDENTIALS not set causes silent auth failures; always export the path to a valid service account JSON or run gcloud auth application-default login.
• ESM/CJS interop: gaxios and gax ship ESM with .js extensions; if your project uses "type": "commonjs", use import() dynamic imports or set "moduleResolution": "bundler" in tsconfig.json.
• @grpc/grpc-js version mismatch: google-gax pins a specific @grpc/grpc-js range; running multiple versions causes Channel class conflicts - use npm dedupe or resolutions in package.json.
• jsdoc-region-tag requires CJS require(): it is not an ES module; do not import it with static imports in an ESM project - use createRequire from node:module.
• SAMPLES_DIRECTORY defaulting to ./samples: if your samples live elsewhere, set the env var before calling loadSampleCache(), or the cache will be empty with no error thrown.
• TypeScript path aliases not applied at runtime: tsconfig paths are compile-time only; add tsconfig-paths or use tsc-alias to rewrite paths in output, or use the published npm packages instead of vendored source.

Vibe-coding prompt template

I have a directory called `source/` in my project root that contains the
google-cloud-node monorepo (upstream package: google-cloud-node).
I also have a file `USAGE.md` in my project root that describes the public API,
real exports, and working examples for this block.

Please read `USAGE.md` and `source/core/common/src/index.ts`,
`source/core/packages/gax/src/index.ts`, and
`source/core/packages/gaxios/src/index.ts` to understand the available exports.

Then integrate the following into my existing [Express/Fastify/Next.js] project:

1. Install all required dependencies listed in USAGE.md.
2. Configure tsconfig.json paths if I am vendoring source/ directly, or use
   the npm packages (@google-cloud/common, google-gax, gaxios).
3. Set up Google Application Default Credentials using GOOGLE_APPLICATION_CREDENTIALS.
4. Create a module at src/gcp/client.ts that:
   - Uses `request` from gaxios to call [MY_GCP_REST_ENDPOINT]
   - Handles GaxiosError with a fallback response
   - Is typed with the GaxiosOptions and GaxiosResponse interfaces
5. If I need a custom resource class, extend Service and ServiceObject from
   @google-cloud/common as shown in USAGE.md.
6. Walk me through each step, show the exact file changes, and confirm imports
   match the real exports visible in USAGE.md.

License and credit

This block is derived from the google-cloud-node monorepo, published by Google LLC under the Apache License 2.0. See source/LICENSE for the full license text. Individual packages retain their own license headers. Upstream repository: https://github.com/googleapis/google-cloud-node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Google APIs Node.js Client Library

Automation, Utilities & Developer Tools

Free