Before connecting your app to the Cloud Storage for Firebase emulator, make sure
that you [understand the overall Firebase Local Emulator Suite workflow](https://firebase.google.com/docs/emulator-suite/connect_and_prototype.md.txt?database=Firestore),
and that you [install and configure](https://firebase.google.com/docs/emulator-suite/install_and_configure.md.txt)
the Local Emulator Suite and review its [CLI commands](https://firebase.google.com/docs/emulator-suite/install_and_configure.md.txt#startup).

## Choose a Firebase project

The Firebase Local Emulator Suite emulates products for a single Firebase project.

To select the project to use, before you start the emulators, in the CLI run
`firebase use` in your working directory. Or, you can pass
the `--project` flag to each emulator
command.

> [!NOTE]
> **Note:** It's generally a good practice to use one project ID for all emulator invocations, so the Emulator Suite UI, different product emulators, and all running instances of a particular emulator can communicate correctly in all cases. In fact, by default, the Local Emulator Suite will warn on detecting multiple project IDs in use, though you can override this behavior. For guidance on setting and managing project IDs, see the [Installation and configuration guide](https://firebase.google.com/docs/emulator-suite/install_and_configure.md.txt#project_id_configuration).

Local Emulator Suite supports emulation of *real* Firebase projects and
*demo* projects.

| Project type | Features | Use with emulators |
|---|---|---|
| Real | A real Firebase project is one you created and configured (most likely via the Firebase console). Real projects have live resources, like database instances, storage buckets, functions, or any other resource you set up for that Firebase project. | When working with real Firebase projects, you can run emulators for any or all of the supported products. For any products you are not emulating, your apps and code will interact with the *live* resource (database instance, storage bucket, function, etc.). |
| Demo | A demo Firebase project has no *real* Firebase configuration and no live resources. These projects are usually accessed via codelabs or other tutorials. Project IDs for demo projects have the `demo-` prefix. | When working with demo Firebase projects, your apps and code interact with emulators *only*. If your app attempts to interact with a resource for which an emulator isn't running, that code will fail. |

We recommend you use demo projects wherever possible. Benefits include:

- Easier setup, since you can run the emulators without ever creating a Firebase project
- Stronger safety, since if your code accidentally invokes non-emulated (production) resources, there is no chance of data change, usage and billing
- Better offline support, since there is no need to access the internet to download your SDK configuration.

> [!NOTE]
> **Note:** If you want to emulate cross-service interactions such as database-triggered Cloud Functions or Security Rules that rely on Authentication you must make sure that the project ID in your code (in `initializeApp()`, etc.) matches the project ID used by the Firebase CLI.

## Instrument your app to talk to the emulators

### Android, Apple platforms, and Web SDKs

Set up your in-app configuration or test classes to interact with the
Cloud Storage for Firebase emulator as follows.

##### Kotlin

```kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val storage = Firebase.storage
storage.useEmulator("10.0.2.2", 9199)
```

##### Java

```java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseStorage storage = FirebaseStorage.getInstance();
storage.useEmulator("10.0.2.2", 9199);
```

##### Swift

```swift
Storage.storage().useEmulator(withHost: "127.0.0.1", port: 9199)
```

##### Unity

> [!NOTE]
> The default host is `127.0.0.1`. If you are using an Android emulator, you need to use `10.0.2.2`.

```c#
FirebaseStorage storage = FirebaseStorage.DefaultInstance;
// Connects to the Storage Emulator running on port 9199
storage.UseEmulator("127.0.0.1", 9199);
```

### Web

```javascript
const { getStorage, connectStorageEmulator } = require("firebase/storage");

const storage = getStorage();
if (location.hostname === "localhost") {
  // Point to the Storage emulator running on localhost.
  connectStorageEmulator(storage, "127.0.0.1", 9199);
} 
```

### Web

> [!NOTE]
> [Learn
> more](https://firebase.google.com/docs/web/learn-more#modular-version) about the tree-shakeable modular Web API and its advantages over the namespaced API.

```javascript
var storage = firebase.storage();
if (location.hostname === "localhost") {
  // Point to the Storage emulator running on localhost.
  storage.useEmulator("127.0.0.1", 9199);
} 
```

No additional setup is needed to test Cloud functions [triggered by Cloud Storage for Firebase events](https://firebase.google.com/docs/storage/extend-with-functions.md.txt)
using the emulator. When the Cloud Storage for Firebase and Cloud Functions
emulators are both running, they automatically work together.

### Admin SDKs

The Firebase Admin SDKs automatically connect to the Cloud Storage for Firebase
emulator when the `FIREBASE_STORAGE_EMULATOR_HOST` environment variable is set:

```bash
export FIREBASE_STORAGE_EMULATOR_HOST="127.0.0.1:9199"
```

> [!NOTE]
> **Note:** For emulators to work correctly the `FIREBASE_STORAGE_EMULATOR_HOST` environment variable must omit protocols such as `http://`.

Note that the Cloud Functions emulator is automatically aware of the
Cloud Storage for Firebase emulator so you can skip this step when testing
integrations between Cloud Functions and Cloud Storage for Firebase
emulators. The environment variable will be automatically set for the Admin SDK
in Cloud Storage for Firebase.

If you want your Admin SDK code to connect to a shared emulator running in
another environment, you will need to specify the [the same project ID you set using the Firebase CLI](https://firebase.google.com/docs/emulator-suite/connect_storage.md.txt#choose_a_firebase_project).
You can pass a project ID to `initializeApp` directly or set the
`GCLOUD_PROJECT` environment variable.

##### Node.js Admin SDK

```javascript
admin.initializeApp({ projectId: "your-project-id" });
```

##### Environment Variable

```
export GCLOUD_PROJECT="your-project-id"
```

## Import and export data

The database and Cloud Storage for Firebase emulators allow you to export data
from a running emulator instance. Define a baseline set of data to use in your
unit tests or continuous integration workflows, then export it to be shared
among the team.

```bash
firebase emulators:export ./dir
```

In tests, on emulator startup, import the baseline data.

```bash
firebase emulators:start --import=./dir
```

You can instruct the emulator to export data on shutdown, either specifying an
export path or simply using the path passed to the `--import`
flag.

```bash
firebase emulators:start --import=./dir --export-on-exit
```

These data import and export options work with the
`firebase emulators:exec` command as well. For more, refer to the
[emulator command reference](https://firebase.google.com/docs/emulator-suite/install_and_configure.md.txt#startup).

## How the Cloud Storage for Firebase emulator differs from production

For testing of client apps, the Cloud Storage for Firebase emulator aligns to
production almost perfectly in regards to the Firebase API surface area. All
Firebase commands are expected to work between the regular Firebase SDKs (Web,
Android, and Apple platforms).

For testing of server-side apps, limitations exist. The Firebase Admin SDKs
make use the Google Cloud API surface, and not all endpoints of this API are
emulated. As a rule of thumb, anything which can be done from the client SDKs
(uploading or deleting files, getting and setting metadata) is also implemented
for use from the Admin SDKs, but anything beyond that is not. Notable exclusions
are listed below.

### Differences from Google Cloud Storage

The Cloud Storage for Firebase product, including the Storage emulator, provides
a subset of Google Cloud Storage (GCS) functionality focusing on storage objects
that is very useful for developing Firebase apps. Cloud Storage for Firebase
differs from GCS in the following ways:

- Cloud Storage for Firebase does not currently support `Bucket` APIs for creating, listing, getting, or deleting storage buckets.
- From the [Google Cloud Storage Objects API](https://cloud.google.com/storage/docs/json_api/v1/objects#methods), the following methods are supported: `copy`, `delete`, `get`, `insert`, `list`, `patch`, `rewrite`, `update`.

### Cloud IAM

The Firebase Emulator Suite does not attempt to replicate or respect any
IAM-related behavior for running. Emulators adhere to the Firebase Security
Rules provided, but in situations where IAM would normally be used, for example
to set Cloud Functions invoking service account and thus permissions, the
emulator is not configurable and will use the globally-available account on
your developer machine, similar to running a local script directly.

### Pub/Sub notifications

The Cloud Storage for Firebase emulator does not integrate with the Cloud
Pub/Sub emulator and thus does not support creating
channels/notifications for storage object changes. We recommend using
Cloud Functions Storage triggers directly.

### Bucket-level metadata

The Cloud Storage for Firebase emulator does not support any bucket-level
configuration including storage class, bucket-level CORS configuration, labels,
or retention policies. Firebase intends to improve this support over time.

## What next?

- For a curated set of videos and detailed how-to examples, follow the [Firebase Emulators Training Playlist](https://firebase.google.com/learn/pathways/firebase-emulators.md.txt).
- Since triggered functions are a typical integration with Cloud Storage for Firebase, learn more about the Cloud Functions for Firebase emulator at [Run functions locally](https://firebase.google.com/docs/functions/local-emulator.md.txt).