Google Drive

Google Drive via the official Drive v3 client. Maps unified string keys onto Drive's appProperties with a per-instance LRU cache.

Installation

@googleapis/drive and google-auth-library are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @googleapis/drive google-auth-library

pnpm add files-sdk @googleapis/drive google-auth-library

yarn add files-sdk @googleapis/drive google-auth-library

bun add files-sdk @googleapis/drive google-auth-library

Google Drive via the official @googleapis/drive v3 client. Drive is a document manager rather than object storage - files have opaque fileIds and names can collide, so the adapter maps a unified string key onto Drive’s appProperties (fsdkKey), with a per-instance LRU so reads after the first don’t re-issue a lookup. Four auth modes: service-account credentials (inline or via key file), an OAuth refresh token, a pre-built Drive client (the escape hatch), or env-var fallback.

import { Files } from "files-sdk";
import { googleDrive } from "files-sdk/google-drive";

// Service account into a Shared Drive (recommended - the default
// service-account quota is 15 GB and not really intended for storage).
// Add the service account as a member of the Shared Drive in the
// Google Workspace admin console first.
const files = new Files({
  adapter: googleDrive({
    credentials: {
      client_email: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
      private_key: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
    },
    driveId: process.env.GOOGLE_DRIVE_ID!,
    // Shared Drive root id, or a sub-folder id to scope the "bucket".
    rootFolderId: process.env.GOOGLE_DRIVE_ID!,
    // publicByDefault: true → grants anyone-with-link reader on upload
    //                       and url() returns the Drive download URL.
  }),
});

Options

PropType

credentials?{ client_email: string; private_key: string }

Inline service-account credentials. Mints a `JWT` auth client with `https://www.googleapis.com/auth/drive` scope. Mutually exclusive with the other auth shapes.

Type{ client_email: string; private_key: string }

keyFilename?string

Path to a service-account JSON file. Mutually exclusive with the other auth shapes.

Typestring

oauth?{ clientId: string; clientSecret: string; refreshToken: string }

OAuth refresh token (3-legged OAuth, end-user Drive). The adapter mints fresh access tokens against `clientId`/`clientSecret`. Mutually exclusive with the other auth shapes.

Type{ clientId: string; clientSecret: string; refreshToken: string }

client?drive_v3.Drive

Pre-built `@googleapis/drive` v3 client — escape hatch for callers that have already wired auth (workload identity, ADC, etc.). When passed, the adapter uses it directly. `signedUploadUrl()` requires an auth handle to mint access tokens for the resumable session POST; if you use this escape hatch, that method will throw because we can't recover the underlying auth from the wrapped client in a stable way.

Typedrive_v3.Drive

subject?string

Domain-wide delegation subject (the user to impersonate). Only honored with `credentials` or `keyFilename`.

Typestring

driveId?string

Shared Drive id. **Strongly recommended for service-account auth** — service accounts have a 15 GB personal quota; production workloads should target a Shared Drive with the service account added as a member. When set, all queries scope to that Shared Drive.

Typestring

rootFolderId?string

Logical "bucket root" — virtual keys live under this folder. Defaults to `"root"` (My Drive root) or, when `driveId` is set, the Shared Drive root id should be used here.

Typestring

publicByDefault?boolean

When `true`, `upload()` also creates an `anyone with link, reader` permission and `url()` returns the Drive public download URL. When `false` (default), `url()` throws — Drive has no signed URL primitive. Security note: this is public-by-default for the entire adapter lifetime. If you need a mix of public and private files, instantiate two `Files` instances or grant permissions explicitly via `raw`.

Typeboolean

fileIdCacheSize?number

LRU capacity for the in-memory virtual-key → fileId cache. Drive has no native key field; every read after the first round-trips a `files.list` to resolve the id, which the cache amortizes within a single adapter instance. Defaults to 1024.

Typenumber

Limitations

Two files with the same virtual key (created out-of-band) make resolution throw Conflict rather than picking one silently. User metadata keys starting with fsdk are reserved - the adapter uses that prefix on Drive’s appProperties for bookkeeping.

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	⚠️	Drive has no native key field. The adapter scopes by parent folder and filters client-side to files carrying its `fsdkKey` appProperty - files written into the same folder out-of-band are excluded. `prefix` is filtered page-local and can under-return when the prefix isn’t satisfied within a single page.
`search`	⚠️	Built on `listAll` — inherits this adapter’s `list` behavior above. Client-side key match (glob, regex, substring, exact).
`head`	✅
`exists`	⚠️	Drive has no native key field. The adapter resolves by parent folder + `fsdkKey` appProperty, so files written into the same folder out-of-band return `false` even if a file with that name exists.
`copy`	✅
`url`	⚠️	Throws by default - Drive has no signed URL primitive. With `publicByDefault: true` at construction, `upload()` grants `anyone, reader` and `url()` returns the permanent Drive download URL (`expiresIn` ignored). `responseContentDisposition` always throws - Drive’s download URL has no Content-Disposition override.
`signedUploadUrl`	⚠️	Initiates a Drive resumable session via `POST /upload/drive/v3/files?uploadType=resumable` and returns the session URL as a one-shot PUT. `maxSize` and `minSize` throw because Drive sessions do not enforce a server-side `content-length-range` policy; enforce size limits at your application gateway instead. Throws when the adapter was constructed via the pre-built `client` escape hatch (no auth handle to mint access tokens).

Google Drive

Installation

Usage

Options

Limitations

Compatibility