Google Cloud Storage

Google Cloud Storage via the official @google-cloud/storage SDK. Application Default Credentials by default.

Installation

@google-cloud/storage is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @google-cloud/storage

pnpm add files-sdk @google-cloud/storage

yarn add files-sdk @google-cloud/storage

bun add files-sdk @google-cloud/storage

Usage

import { Files } from "files-sdk";
import { gcs } from "files-sdk/gcs";

const files = new Files({
  adapter: gcs({
    bucket: "uploads",
    // No credentials needed in most setups - the @google-cloud/storage
    // SDK auto-discovers Application Default Credentials from
    // GOOGLE_APPLICATION_CREDENTIALS, gcloud auth, or the runtime
    // service account on Cloud Run / GKE / GCE.
  }),
});

upload reports true byte-level progress via onProgress. Uploads default to a single simple request; when onProgress is passed, the adapter switches to a resumable upload (the only path that emits progress), which adds one round trip.

Options

PropType

bucketstring

GCS bucket name. The adapter scopes all operations to it.

Typestring

projectId?string

GCP project ID. Falls back to `GOOGLE_CLOUD_PROJECT` then `GCLOUD_PROJECT`. Optional — Application Default Credentials carry a project ID and the SDK will discover it automatically.

Typestring

keyFilename?string

Path to a service-account JSON file. When set, takes precedence over ADC. Mutually exclusive with `credentials` in practice; if both are passed, the SDK uses `credentials`.

Typestring

credentials?{ client_email: string; private_key: string }

Inline service-account credentials. Useful when you only have `client_email` + `private_key` available as separate env vars (e.g. Vercel/Netlify) and don't want to materialize a JSON file. When neither this nor `keyFilename` is set, the SDK falls back to ADC (`GOOGLE_APPLICATION_CREDENTIALS`, `gcloud auth`, GCE metadata).

Type{ client_email: string; private_key: string }

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — appropriate for a public bucket or a CDN in front of GCS. When unset, `url()` falls back to a V4 signed read URL (default expiry: 1 hour). For a public GCS bucket, the natural value is `https://storage.googleapis.com/<bucket>`.

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the V4 signed URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour). Per-call `url(key, { expiresIn })` overrides. GCS V4 caps at 7 days.

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅