The Firebase Local Emulator Suite can be installed and configured for different prototype and test environments, anything from one-off prototyping sessions to production-scale continuous integration workflows.
Install the Local Emulator Suite
Before installing the Emulator Suite you will need:
To install the Emulator Suite:
- Install the Firebase CLI.
If you don't already have the Firebase CLI installed,
install it now.
You will need CLI version 8.14.0 or higher to use the Emulator Suite. You can
check which version you have installed using the following command:
firebase --version
- If you haven't already done so, initialize the current working directory
as a Firebase project, following the onscreen prompts to specify which
products to use:
firebase init
- Set up the Emulator Suite. This command starts a configuration wizard that
lets you select emulators of interest, download the corresponding emulator
binary files, and set emulator ports if the defaults are not appropriate.
firebase init emulators
Once an emulator is installed, no update checks are performed and no additional automatic downloads will occur until you update your Firebase CLI version.
Configure Emulator Suite
You can optionally configure the emulators' network ports and path to Security
Rules definitions in the firebase.json
file
If you don't configure these settings, the emulators will listen on their default ports, and the Cloud Firestore and Realtime Database emulators will run with open data security.
Change emulator ports by running firebase init emulators
or by editing
firebase.json
manually. Change the path to Security Rules definitions by
editing firebase.json
manually.
Command | Description |
---|---|
init emulators | Start an emulator initialization wizard. Identify emulators to be installed and optionally specify emulator port settings. init emulators is non-destructive; accepting defaults will preserve the current emulator configuration. |
Port configuration
Each emulator binds to a different port on your machine with a preferred default value.
Emulator | Default Port |
---|---|
Authentication | 9099 |
Emulator Suite UI | 4000 |
Cloud Functions | 5001 |
Realtime Database | 9000 |
Cloud Firestore | 8080 |
Pub/Sub | 8085 |
Firebase Hosting | 5000 |
Security Rules configuration
The emulators will take Security Rules configuration from the database
and firestore
configuration keys in firebase.json
.
{
// Existing firebase configuration ...
"database": {
"rules": "database.rules.json"
},
"firestore" {
"rules": "firestore.rules"
},
// ...
// Optional emulator configuration. Default
// values are used if absent.
"emulators": {
"firestore": {
"port": "8080"
},
"ui": {
"enabled": true, // Default is `true`
"port": 4000 // If unspecified, see CLI log for selected port
},
"auth": {
"port": "9099"
},
"functions": {
"port": "5001"
},
"database": {
"port": "9000"
},
"pubsub": {
"port": "8085"
}
}
}
Start up emulators
You can start emulators to run until manually terminated, or to run for the duration of a designated test script then automatically shut down.
Command | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
emulators:start | Start emulators for the Firebase products configured in firebase.json .
Emulator processes will continue running until explicitly stopped. Calling
emulators:start will download the emulators to ~/.cache/firebase/emulators/ if
they are not already installed.
|
||||||||||||
emulators:exec scriptpath | Run the script at scriptpath after starting emulators for the Firebase products
configured in firebase.json . Emulator processes will automatically stop when the
script has finished running.
|
The firebase emulators:exec
method is generally more appropriate for continuous integration workflows.
Export and import emulator data
You can export data from the Cloud Firestore emulator to use as a shareable,
common baseline data set. These data sets can be imported using the
--import
flag, as described above.
emulators:export export_directory |
Cloud Firestore or Realtime Database emulator. Export data from a running
Cloud Firestore or Realtime Database emulator instance. The specified
You can instruct the emulators to export data automatically when they shutdown using the
|
Integrate with your CI system
Running containerized Emulator Suite images
Installation and configuration of the Emulator Suite with containers in a typical CI setup is straightforward.
There are a few issues to note:
JAR files are installed and cached at
~/.cache/firebase/emulators/
.- You may want to add this path to your CI cache configuration to avoid repeated downloads.
If you do not have a
firebase.json
file in your repository, you must add a command line argument to theemulators:start
oremulators:exec
command to specify which emulators should be started. For example,--only functions,firestore
.
Generate an auth token (Hosting emulator only)
If your continuous integration workflows rely on Firebase Hosting, then you will need to login using a token in order to run firebase emulators:exec
. The other emulators do not require login.
To generate a token, run firebase login:ci
on your local environment; this should not be performed from a CI system. Follow instructions to authenticate. You should only need to perform this step once per project, since the token will be valid across builds. The token should be treated like a password; make sure it is kept secret.
If your CI environment allows you to specify environment variables that can be used in the build scripts, simply create an environment variable called FIREBASE_TOKEN
, with the value being the access token string. The Firebase CLI will automatically pick up the FIREBASE_TOKEN
environment variable and the emulators will start properly.
As a last resort, you can simply include the token in your build script, but make sure that untrusted parties do not have access. For this hard-coded approach, you can add --token "YOUR_TOKEN_STRING_HERE"
to the firebase emulators:exec
command.
Use the Emulator Hub REST API
List running emulators
To list the currently running emulators, send a GET
request to the /emulators
endpoint of the Emulator Hub.
curl localhost:4400/emulators
The result will be a JSON object listing all running emulators and their host/port configuration, for example:
{
"hub":{
"name": "hub",
"host": "localhost",
"port": 4400
},
"functions": {
"name": "functions",
"host": "localhost",
"port": 5001
}
"firestore": {
"name": "firestore",
"host": "localhost",
"port": 8080
}
}
Enable / Disable Background Function Triggers
In some situations you will need to temporarily disable local function triggers.
For example you may want to delete all of the data in the Cloud Firestore
emulator without triggering any onDelete
functions that are running
in the Cloud Functions emulator.
To temporarily disable local function triggers, send a PUT
request to the
/functions/disableBackgroundTriggers
endpoint of the Emulator Hub.
curl -X PUT localhost:4400/functions/disableBackgroundTriggers
The result will be a JSON object detailing the current state.
{
"enabled": false
}
To enable local function triggers after they have been disabled, send a PUT
request to the /functions/enableBackgroundTriggers
endpoint of the Emulator
Hub.
curl -X PUT localhost:4400/functions/enableBackgroundTriggers
The result will be a JSON object detailing the current state.
{
"enabled": true
}
Emulator SDK integrations
The tables in this section indicate which emulators are supported by client and Admin SDKs. Future means emulator support is planned but not yet available.
Client SDK availability
Android | iOS | Web |
Firebase UI Android |
Firebase UI iOS |
Firebase UI Web |
|
---|---|---|---|---|---|---|
Realtime Database | 19.4.0 | 7.2.0 | 8.0.0 | 6.4.0 | Future | N/A |
Cloud Firestore | 21.6.0 | 7.2.0 | 8.0.0 | 6.4.0 | Future | N/A |
Authentication | 20.0.0 | 7.0.0 | 8.0.0 | 7.0.0 | Future | Future |
Cloud Functions | 19.1.0 | 7.2.0 | 8.0.0 | N/A | N/A | N/A |
Hosting | N/A | N/A | N/A | N/A | N/A | N/A |
Admin SDK availability
Node | Java | Python | Go | |
---|---|---|---|---|
Realtime Database | 8.6.0 | 6.10.0 | 2.18.0 | Future |
Cloud Firestore | 8.0.0 | 6.10.0 | 3.0.0 | 1.0.0 |
Authentication | 9.3.0 | Future | Future | Future |
Cloud Functions | N/A | N/A | N/A | N/A |
Hosting | N/A | N/A | N/A | N/A |