Firebase Emulator UI

If you want to iterate on the UI while connected to your own project's emulators, follow these steps:

1. In your project directory, start the emulators:

cd project/
firebase emulators:start --import my-data

2. In a separate terminal, navigate to the firebase-tools-ui directory and start the dev server, providing your project ID and the emulator hub address:

cd firebase-tools-ui/
GCLOUD_PROJECT=<project-id> FIREBASE_EMULATOR_HUB=localhost:4400 npm start

Note: The development server runs on port 5173 by default. Do not confuse this with the production Emulator UI, which defaults to port 4000.

To develop the Emulator UI using pre-defined test data, use the firebase emulators:exec command. This ensures the necessary environment variables are set so the web application can communicate with the emulators.

1. Clone the repository and install dependencies:

git clone https://github.com/firebase/firebase-tools-ui.git
cd firebase-tools-ui
npm install

2. Run the development server:

firebase emulators:exec --project demo-example --import test-data 'npm start'

3. Access the UI at http://localhost:5173.

The Firebase Emulator UI is a web interface for the Firebase Emulator Suite. It provides an overview of running emulators, a Data Viewer/Editor for Firebase Realtime Database and Cloud Firestore, and a Logs Viewer with filters.

To use it, follow the standard guide for installing and running the Emulator Suite.

Requirements:

• Firebase CLI version >= 8.4.0.

The Emulator UI starts automatically when you start the Emulator Suite.

The Realtime Database UI uses a specific URL pattern to navigate namespaces and data paths. This allows for deep-linking into specific nodes of the database.

URL Patterns:

• Base Redirect: Navigating to the base database path (e.g., /${url}/${projectId}) automatically redirects to the /data endpoint.
• Namespace and Data Path: The primary routing pattern is /${path}/:namespace/data/:path*.

Example Path Construction: If the base URL is /database and the project ID is my-project, the path to a specific node users/123 in a namespace default would be: /database/default/data/users/123

The Firestore UI provides a mechanism to clear all data from the current database. This is triggered via the handleClearData function which:

1. Prompts the user for confirmation using promptClearAll().
2. If confirmed, calls eject() from the useEjector hook to reset the emulator state.
3. Navigates the user back to the database root.

An ExpressionPathSegmentValue represents a single segment within a path expression. Segments can be one of three types:

1. Simple Path: A direct path segment (e.g., /simple).
2. Capture: A single-segment capture expression (e.g., /{name}). It includes a variableName and an optional boundValue (a URL-decoded string).
3. Glob Capture: A multi-segment capture expression using glob syntax (e.g., /{name=**}). It includes a variableName and a boundValue which is itself a list of ExpressionPathSegmentValue segments.

The Firestore Emulator UI supports multiple databases by modifying the databaseId in the URL path. The routing structure follows this pattern:

• Data View: /firestore/:databaseId/data (e.g., /firestore/default/data)
• Requests View: /firestore/:databaseId/requests (e.g., /firestore/default/requests)

If you navigate to /firestore without a database ID, the UI redirects to /firestore/default/data by default.

To use the DocumentEditor for Realtime Database instead of Firestore, pass the rtdb prop as true. This changes the allowed child types for maps and arrays to follow RTDB rules (which include JSON types and different constraints on nested structures).

<DocumentEditor
  value={rtdbData}
  rtdb={true}
  onChange={handleUpdate}
/>

The EmulatorV1ProjectsConfig interface defines the configuration for the Authentication emulator, mirroring the Firebase CLI configuration. Currently, it supports configuring email sign-in behavior.

interface EmulatorV1ProjectsConfig {
  signIn: {
    allowDuplicateEmails: boolean;
  };
}

const config: EmulatorV1ProjectsConfig = {
  signIn: {
    allowDuplicateEmails: false
  }
};

The npm run build command generates production assets for both the server and the web client.

• Web Client: Output is located in dist/client. It is minified, optimized, and includes content hashes in filenames.
• Server: Output is located in dist/server/server.js. This is a standalone Node.js file containing all dependencies.

To run the production build with emulators:

firebase emulators:exec --project demo-example --import test-data 'node dist/server/server.js'

This starts a server that serves both the static files and APIs at http://localhost:5173/.

Warning: The static files in dist/client are not intended for direct deployment to a CDN or website; they must be served via the production server described above.

To run tests in an environment with emulators, use firebase emulators:exec.

Run all tests:

firebase emulators:exec --project demo-test 'npm test'

Run a specific test file (e.g., for Firestore):

firebase emulators:exec --project demo-test --only firestore 'npm test AddCollectionDialog.test.tsx'

Run tests without interactive watch mode:

firebase emulators:exec --project demo-test --only firestore 'npm test -- --watchAll=false'

Note: If you encounter port conflict errors, ensure other instances of the Firebase Emulator Suite are stopped.