firebase-storage

library1.1.4jsnpmunverified

A lightweight Node.js library for interacting with Google Cloud Storage using Firebase service account credentials (private key). Version 1.1.4 supports file upload, download, list, info, delete, bucket info, and bucket update operations. Designed for Edge runtime compatibility, it uses the official google-auth-library for authentication and simplifies bucket/file management. Unlike the main Firebase Admin SDK, this package focuses exclusively on storage with a minimal API and supports parallel uploads (configurable). Released under MIT license, actively maintained.

storage

npm install firebase-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FIREBASE-STORAGE

firebase-storage

storagejavascriptv1.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getStorage

✓ import { getStorage } from 'firebase-storage'

✗ import getStorage from 'firebase-storage'

Default export is not available; only named export 'getStorage' exists.

Storage

✓ import type { Storage } from 'firebase-storage'

✗ import { Storage } from 'firebase-storage'

Storage is a TypeScript type (interface), not a runtime value. Use type import.

getStorage

✓ const { getStorage } = require('firebase-storage')

✗ const getStorage = require('firebase-storage')

Library is ESM-first; require() works but must destructure named export.

Demonstrates basic upload, info, download, and delete operations using a service account with private key.

const { getStorage } = require('firebase-storage'); const privateKey = process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n') ?? ''; const clientEmail = process.env.FIREBASE_CLIENT_EMAIL ?? ''; const bucket = process.env.FIREBASE_STORAGE_BUCKET ?? ''; async function main() { const storage = getStorage({ privateKey, clientEmail, bucket }); const file = new Blob(['Hello world'], { type: 'text/plain' }); await storage.upload({ name: 'hello.txt', file, published: true }); const info = await storage.info({ name: 'hello.txt' }); console.log('Uploaded:', info); const data = await storage.download({ name: 'hello.txt' }); console.log('Content:', new TextDecoder().decode(data)); await storage.del({ name: 'hello.txt' }); } main().catch(console.error);

Debug

Known issues

gotchaPrivate key must have newlines replaced with \n when passed as environment variable.

fix

Use process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n') to restore actual newlines.

affects: >=1.0.0

gotchaSetting `parallels: 5` limits concurrent uploads when uploading multiple files; default is 1000 which may cause resource issues.

fix

Explicitly set 'parallels' option to a reasonable number (e.g., 5) for controlled concurrency.

affects: >=1.0.0

deprecatedThe 'published' option in upload is deprecated; use 'public' instead in future versions.

fix

Replace `{ published: true }` with `{ public: true }`.

affects: >=1.1.0

breakingIn v1.0.0, the 'getStorage' function required a different parameter shape (bucket was not required).

fix

Update to v1.1+ and provide bucket in options or in each operation.

affects: >=1.0.0 <1.1.0

gotchaThe library is ESM-only for Node.js; using require() with TypeScript may require esModuleInterop.

fix

Set `esModuleInterop: true` in tsconfig.json if using require() in TypeScript.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Unable to parse private key. Ensure it is in PEM format and newlines are replaced with \n.

Private key string contains literal '\n' instead of actual newline characters.

fix

Replace '\n' with actual newlines: const privateKey = process.env.PRIVATE_KEY.replace(/\\n/g, '\n');

Error: The upload function must receive a file of type Blob, Buffer, or string.

Passed a file object that is not a Blob, Buffer, or string.

fix

Ensure file is created with `new Blob([...])` or `Buffer.from(...)`.

TypeError: Cannot read properties of undefined (reading 'replace')

Private key or client email environment variable is undefined.

fix

Set FIREBASE_PRIVATE_KEY and FIREBASE_CLIENT_EMAIL environment variables.

Error: The caller does not have permission

Incorrect or missing service account email or wrong bucket name.

fix

Verify clientEmail and bucket, and ensure the service account has Storage Object Admin role.

Upgrade

Version history

1.1.4latest on npm

Audit

Dependencies

google-auth-libraryrequiredUsed for authenticating with Google Cloud Storage using service account credentials.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/node-libraries/firebase-storage ↗

packagefirebase-storage ↗

homepagehttps://github.com/node-libraries/firebase-storage#readme ↗