Test web apps locally with the Firebase App Hosting Emulator

You can perform local tests of your app prior to App Hosting deployment using the App Hosting emulator, which is part of the Firebase Local Emulator Suite.

Before using the App Hosting emulator, make sure that you understand the overall Firebase Local Local Emulator Suite workflow, and that you install and configure the Local Local Emulator Suite and review its CLI commands.

This topic assumes you are already familiar with App Hosting. If needed, review the App Hosting introduction and other materials to help you understand how App Hosting works.

What can I do with the App Hosting emulator?

The App Hosting emulator lets you test and refine your web applications locally, closely replicating a production environment. This can streamline your development process and enhance the quality of web apps built using Firebase and deployed on App Hosting.

The App Hosting emulator:

  1. Lets you run your web app locally, with environment variables defined in apphosting.yaml configuration files
  2. Can export the secrets you have saved in your different App Hosting environments, allowing you to simulate applications in different environments
  3. Can be used alongside other Firebase emulators. If you're using the Firestore, Auth, or any other emulator, the Local Emulator Suite ensures that these emulators are started first before the App Hosting emulator.

Configure the emulator

To get started, install and initialize the Local Emulator Suite as described in Install, configure and integrate Local Emulator Suite. In addition to any other Firebase emulators that you want to set up, make sure to select App Hosting Emulator. The CLI prompts you for some App Hosting emulator values, including:

firebase init emulators
=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ App Hosting Emulator
 ◯ Firestore Emulator
 ◯ Database Emulator
 ◯ Hosting Emulator
 ◯ Pub/Sub Emulator
 ◯ Storage Emulator
 ◯ Eventarc Emulator
(Move up and down to reveal more choices)

? Specify your app's root directory relative to your project (.)

? What configs would you like to export? (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
 ❯◯ Secrets

? Which environment would you like to export secrets from Secret Manager for?:
  ◯ base (apphosting.yaml)
 ❯◯ staging (apphosting.yaml + apphosting.staging.yaml)
  ◯ preview (apphosting.yaml + apphosting.preview.yaml)

i Wrote Secrets as environment variables to apphosting.local.yaml.
i apphosting.local.yaml has been automatically added to your .gitignore.

Any values you provide in this setup flow are used to update your App Hosting emulator configuration in firebase.json. You can also configure the App Hosting emulator by updating firebase.json directly. The schema for the App Hosting emulator is:

{
  ...
  "emulators": {
    "apphosting": {
      "startCommandOverride": <command> [optional]
      "rootDirectory": <path> [optional]
      }
    }
  }
  • startCommandOverride is automatically generated and set when the emulator is initialized. If not provided, the emulator will detect and run your package manager's dev command.
  • rootDirectory is used to support monorepo project setups. If your web app is in a subdirectory, you need to provide the path of that directory relative to the root (the location of firebase.json).

Manage emulation

Emulator initialization creates an apphosting.local.yaml file in your app's root directory. This configuration file has the same schema as the apphosting.yaml file used in production, but instead is meant strictly for local development. By default, the emulator reads configuration from your apphosting.yaml file, but if an apphosting.local.yaml file is present, then configurations in that file are prioritized and given precedence.

Export secrets to simulate different environments locally

If you are working with multiple environments and want to simulate different app environments locally, you may need the corresponding environments' secrets. You can export secrets for a specific environment using the CLI command apphosting:config:export (alternatively, as shown in Configure the emulator, you can optionally import secrets during emulator initialization).

This command requires you to select from your project's available App Hosting environments. The environment-specific App Hosting configuration (for example, "apphosting.staging.yaml") and the base App Hosting configuration ("apphosting.yaml") are merged, with the environment-specific configuration taking precedence. If secrets with the same name exist in both configurations, the secret from the environment-specific configuration is used.

For example, to export secrets to the emulator from a staging environment:

firebase apphosting:config:export --project <your firebase project Id>

? What configs would you like to export? (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
 ❯◯ Secrets

? Which environment would you like to export secrets from Secret Manager for?:
  ◯ base (apphosting.yaml)
 ❯◯ staging (apphosting.yaml + apphosting.staging.yaml)
  ◯ preview (apphosting.yaml + apphosting.preview.yaml)
i Wrote Secrets as environment variables to apphosting.local.yaml.
i apphosting.local.yaml has been automatically added to your .gitignore.

Your apphosting.local.yaml file is updated (or created if it doesn't exist) with the exported secrets as environment variables. Because the file now contains sensitive information in plain text, it will be automatically added to your .gitignore file to prevent it from being accidentally committed to your source code repository.

Run the emulator

firebase emulators:start

This will start all the emulators defined in your firebase.json file including the App Hosting emulator.