Before you start prototyping and testing your web app with the
Firebase Hosting emulator, make sure that you
understand the overall Firebase Local Emulator Suite workflow
,
and that you
install and configure
the Local Emulator Suite and review its
CLI commands
.
You should also be familiar with the features and implementation workflow
for Firebase Hosting. Start with the
introduction to Firebase Hosting
.
What can I do with the Firebase Hosting emulator?
The Firebase Hosting emulator provides high-fidelity local emulation of
Hosting services, providing much of the functionality found in
production Hosting
. The Hosting emulator
lets you:
- Prototype your static sites and web apps without incurring storage or access
charges
- Prototype, test and debug HTTPS functions before deploying to your Hosting
site
- Test sites and web apps in containerized, continuous integration workflows.
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.
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.
Core prototyping workflow
If you're making quick iterations or you want your app to interact with
emulated backend project resources, you can test your Hosting content and
config locally. When testing locally, Firebase serves your web app at a locally
hosted URL.
(Optional)
By default, your locally hosted app will interact with
real
,
not
emulated
, project resources (functions, database, rules, etc.).
You can instead optionally connect your app to use any
emulated
project
resources that you've configured. Learn more:
Realtime Database
|
Cloud Firestore
|
Cloud Functions
From the root of your local project directory, run the following command:
firebase emulators:start
Open your web app at the local URL returned by the CLI (usually
http://localhost:5000
).
To update the local URL with changes, refresh your browser.
Test from other local devices
By default, the emulators only respond to requests from
localhost
. This
means that you'll be able to access your hosted content from your computer's web
browser but not from other devices on your network. If you'd like to test from
other local devices, configure your
firebase.json
like so:
"emulators": {
// ...
"hosting": {
"port": 5000
"host": "0.0.0.0"
}
}
Generate auth tokens for continuous integration workflows
If your continuous integration workflows rely on Firebase Hosting, then you will
need to log in 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.
What next?