Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Firebase Storage

Firebase Cloud Storage via the official firebase-admin SDK. Underlying client is @google-cloud/storage, so V4 signed URLs and POST policy uploads come for free.

Installation

firebase-admin is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk firebase-admin
pnpm add files-sdk firebase-admin
yarn add files-sdk firebase-admin
bun add files-sdk firebase-admin
nub add files-sdk firebase-admin
aube add files-sdk firebase-admin

Usage

Firebase Cloud Storage via the official firebase-admin SDK. The Admin SDK’s getStorage().bucket() returns a @google-cloud/storage Bucket under the hood, so every primitive (server-side copy, V4 signed URLs, POST policy uploads) maps onto the GCS surface - with Firebase-flavoured credential conventions and a default bucket name derived from your project ID.

import { Files } from "files-sdk";
import { firebaseStorage } from "files-sdk/firebase-storage";

const files = new Files({
  adapter: firebaseStorage({
    bucket: "my-project.firebasestorage.app",
    // Credentials, first match wins: `app` (an existing firebase-admin
    // App or @google-cloud/storage Bucket), `serviceAccountPath`,
    // `credentials`, GOOGLE_APPLICATION_CREDENTIALS (any ADC file:
    // service account, workload identity, authorized_user),
    // FIREBASE_CLIENT_EMAIL + FIREBASE_PRIVATE_KEY, then ambient
    // Application Default Credentials (gcloud auth, GCE metadata).
    // The project comes from `projectId` or FIREBASE_PROJECT_ID.
  }),
});

upload reports true byte-level progress via onProgress. As with GCS, passing onProgress switches the upload to a resumable request (the only path that emits progress), which adds one round trip.

Options

PropType
bucket?string

Storage bucket name. Falls back to `FIREBASE_STORAGE_BUCKET`, then `<projectId>.firebasestorage.app` if `projectId` is known. The Firebase console shows the bucket as `<project>.appspot.com` on older projects and `<project>.firebasestorage.app` on newer ones — pass the literal name from the console rather than relying on the default.

Typestring
projectId?string

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

Typestring
credentials?{ clientEmail: string; privateKey: string }

Inline service-account credentials. Useful when you only have `clientEmail` + `privateKey` available as separate env vars (e.g. Vercel/Netlify) and don't want to materialize a JSON file. Credential precedence: `app`, then `serviceAccountPath`, then this option, then `GOOGLE_APPLICATION_CREDENTIALS` (read through Application Default Credentials, so any ADC file type works: service account, workload identity federation, or `authorized_user`), then `FIREBASE_CLIENT_EMAIL` + `FIREBASE_PRIVATE_KEY`, then ambient ADC (e.g. the metadata server). Explicit options always beat environment variables.

Type{ clientEmail: string; privateKey: string }
serviceAccountPath?string

Path to a service-account JSON file (passed to `cert()`, so it must be a service-account key). Takes precedence over inline `credentials` and every environment variable. For other credential files (workload identity federation, `authorized_user`), set `GOOGLE_APPLICATION_CREDENTIALS` instead, which the adapter reads through Application Default Credentials.

Typestring
app?App | Bucket

Existing Firebase {@link App} or `@google-cloud/storage` {@link Bucket}. Highest precedence — when passed, all other credential options are ignored. Useful when the consumer already initializes Firebase elsewhere (e.g. for Firestore/Auth) and wants to share the app.

TypeApp | Bucket
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 Firebase Storage. When unset, `url()` falls back to a V4 signed read URL (default expiry: 1 hour). Firebase's `?alt=media&token=...` download-token URL form is out of scope for v1; reach for `adapter.raw` if you need it.

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
appName?string

Internal Firebase app name. Allows multiple adapter instances pointing at different projects to coexist without the `initializeApp()` "default app already exists" error. Defaults to a stable name derived from the project ID and bucket; only set this if you have a reason.

Typestring

Limitations

Firebase’s ?alt=media&token=... download-token URL form is out of scope for v1 - url() always returns either a V4 signed read URL or your configured publicBaseUrl. Reach for adapter.raw (the underlying @google-cloud/storage Bucket) if you need to mint Firebase download tokens or use any GCS-side feature that isn’t in the unified API. A stream upload without onProgress or multipart goes out as a single streaming request; pass multipart (or onProgress) for a chunked resumable upload, or control for a pause-able upload whose session can be resumed later.

Compatibility

Method Status Notes
upload ✅
download ✅
delete ✅
list ✅
search ✅
head ✅
exists ✅
copy ✅
url ✅ V4 signed URL, or your publicBaseUrl (no expiry). V4 signing caps expiresIn at 7 days (604800 seconds), so a longer one throws; capabilities.signedUrl.maxExpiresIn reports the cap, and the gateway clamps to it.
signedUploadUrl ✅ V4 signed PUT URL, or a V4 POST policy when maxSize is set - same 7-day expiresIn cap.

Was this page helpful?