How to Use Firebase Storage Emulator for Local Development

To use the Firebase Storage Emulator, first start it with the Firebase CLI using firebase emulators:start --only storage. Then configure your app to connect to the emulator by calling connectStorageEmulator(storage, 'localhost', 9199) on your Firebase Storage instance, allowing you to test storage operations locally.

Syntax

The Firebase Storage Emulator is started via the Firebase CLI with the command firebase emulators:start --only storage. In your app code, connect to the emulator by calling connectStorageEmulator(storage, host, port) on your Firebase Storage instance, where host is usually 'localhost' and port defaults to 9199.

This setup redirects storage operations to the local emulator instead of the live Firebase Storage service.

bash and javascript

firebase emulators:start --only storage

// In your app code (JavaScript example):
import { getStorage, connectStorageEmulator } from 'firebase/storage';

const storage = getStorage();
connectStorageEmulator(storage, 'localhost', 9199);

Example

This example shows how to start the Firebase Storage Emulator and configure a simple JavaScript app to upload a file to the emulator instead of the live Firebase Storage.

javascript

// Start the emulator in your terminal:
// firebase emulators:start --only storage

// JavaScript app code:
import { initializeApp } from 'firebase/app';
import { getStorage, ref, uploadBytes, connectStorageEmulator } from 'firebase/storage';

const firebaseConfig = {
  apiKey: 'fake-api-key',
  authDomain: 'fake-project.firebaseapp.com',
  projectId: 'fake-project',
  storageBucket: 'fake-project.appspot.com'
};

const app = initializeApp(firebaseConfig);
const storage = getStorage(app);

// Connect to local emulator
connectStorageEmulator(storage, 'localhost', 9199);

// Create a reference and upload a file
const storageRef = ref(storage, 'test-folder/hello.txt');
const file = new Blob(['Hello Emulator!'], { type: 'text/plain' });

uploadBytes(storageRef, file).then((snapshot) => {
  console.log('Uploaded a blob or file to emulator:', snapshot.metadata.fullPath);
});

Output

Uploaded a blob or file to emulator: test-folder/hello.txt

Common Pitfalls

• Not starting the emulator: Forgetting to run firebase emulators:start --only storage means your app will try to connect to live Firebase Storage.
• Incorrect host or port: Using wrong host or port in connectStorageEmulator causes connection failures. Default port is 9199.
• Mixing emulator and live services: Ensure all storage calls use the emulator connection during testing to avoid accidental live data changes.

javascript

// Wrong way (no emulator connection):
const storage = getStorage(app);
// uploadBytes(storageRef, file) will go to live Firebase Storage

// Right way (connect to emulator):
connectStorageEmulator(storage, 'localhost', 9199);

Quick Reference

Command/Function	Purpose
firebase emulators:start --only storage	Start the Firebase Storage Emulator locally
connectStorageEmulator(storage, 'localhost', 9199)	Connect your app's storage instance to the local emulator
uploadBytes(ref, file)	Upload a file to the connected storage (emulator or live)
ref(storage, 'path/to/file')	Create a reference to a file location in storage

Key Takeaways

Always start the Firebase Storage Emulator with the Firebase CLI before testing.

Use connectStorageEmulator() in your app to redirect storage calls to the emulator.

Default emulator host is 'localhost' and port is 9199 unless configured otherwise.

Do not mix emulator and live Firebase Storage calls during local testing.

The emulator allows safe, fast testing of storage operations without affecting live data.