Customize your Firebase Studio workspace

Firebase Studio lets you to tailor your workspace to your project's unique needs by defining a single .idx/dev.nix configuration file that describes:

  • The system tools that you need to be able to run (for example, from the Terminal), such as compilers or other binaries.
  • The extensions you need installed (for example, programming language support).
  • How your app previews should show up (for example, the commands to run your web server).
  • Global environment variables available to local servers running in your workspace.

See the dev.nix reference for a complete description of what's available.

By adding a .idx/mcp.json (for Gemini in Firebase) or .gemini/settings.json (for Gemini CLI) file to your project, you can also connect to Model Context Protocol (MCP) servers, including the Firebase MCP server.

Nix and Firebase Studio

Firebase Studio uses Nix to define the environment configuration for each workspace. Specifically, Firebase Studio uses:

  • The Nix programming language to describe workspace environments. Nix is a functional programming language. The attributes and package libraries you can define in the dev.nix file follow the Nix attribute set syntax.

  • The Nix package manager to manage the system tools available to your workspace. This is similar to OS-specific package managers such as APT (apt and apt-get), Homebrew (brew), and dpkg.

Because Nix environments are reproducible and declarative, in the context of Firebase Studio, this means you can share your Nix configuration file as part of your Git repository to ensure everyone who works on your project has the same environment configuration.

A basic example

The following example shows a basic environment configuration enabling previews:

{ pkgs, ... }: { # Which nixpkgs channel to use. channel = "stable-23.11"; # or "unstable" # Use https://search.nixos.org/packages to find packages packages = [ pkgs.nodejs_20 ]; # Sets environment variables in the workspace env = { SOME_ENV_VAR = "hello"; }; # Search for the extensions you want on https://open-vsx.org/ and use "publisher.id" idx.extensions = [ "angular.ng-template" ]; # Enable previews and customize configuration idx.previews = { enable = true; previews = { web = { command = [ "npm" "run" "start" "--" "--port" "$PORT" "--host" "0.0.0.0" "--disable-host-check" ]; manager = "web"; # Optionally, specify a directory that contains your web app # cwd = "app/client"; }; }; }; }

Add system tools

To add system tools to your workspace, such as compilers or CLI programs for cloud services, find the unique package ID in the Nix package registry and add it to your dev.nix file's packages object, prefixed with `pkgs.:

{ pkgs, ... }: { # Which nixpkgs channel to use. channel = "stable-23.11"; # or "unstable" # Use https://search.nixos.org/packages to find packages packages = [ pkgs.nodejs_20 ]; ... }

This is different from how you might typically install system packages using OS-specific package managers such as APT (apt and apt-get), Homebrew (brew), and dpkg. Declaratively describing exactly which system packages are needed means Firebase Studio workspaces are easier to share and reproduce.

Use local node binaries

Just like on your local machine, binaries related to locally installed node packages (for example, packages defined in your package.json) can be executed in a Terminal panel by invoking them with the npx command.

As an additional convenience, if you're in a directory with a node_modules folder (such as the root directory of a web project), locally installed binaries can be invoked directly, without the npx prefix.

Add gcloud components

A default configuration of the gcloud CLI for Google Cloud is available to all Firebase Studio workspaces.

If you need additional components, you can add them to your dev.nix file:

{ pkgs }: { packages = [ ... (pkgs.google-cloud-sdk.withExtraComponents [ pkgs.google-cloud-sdk.components.cloud-datastore-emulator ]) ... ]; }

Add IDE extensions

You can install extensions in Firebase Studio using the OpenVSX extension registry in two ways:

  • Use the Extensions panel in Firebase Studio to discover and install extensions. This approach is best for user-specific extensions, such as:

    • Custom color themes
    • Editor emulation, like VSCodeVim

  • Add extensions to your dev.nix file. These extensions will be automatically installed when you share your workspace configuration. This approach is best for project-specific extensions, such as:

    • Programming language extensions, including language-specific debuggers
    • Official extensions for cloud services used in your project
    • Code formatters

For the latter approach, you can include IDE extensions in your dev.nix file by finding the fully-qualified extension ID (of the form <publisher>.<id>) and adding it to the idx.extensions object like so:

{ pkgs, ... }: { ... # Search for the extensions you want on https://open-vsx.org/ and use the format # "<publisher>.<id>" idx.extensions = [ "angular.ng-template" ]; ... }

Add common services

Firebase Studio also offers simplified setup and configuration for common services you may need during development, including:

  • Containers
    • Docker (services.docker.*)
  • Messaging
    • Pub/Sub Emulator (services.pubsub.*)
  • Databases
    • MySQL (services.mysql.*)
    • Postgres (services.postgres.*)
    • Redis (services.redis.*)
    • Spanner (services.spanner.*)

For details on enabling these services in your workspace, see the services.* portions of the dev.nix reference.

Customize previews

For details on how to customize your app previews, see Preview your app.

Set your workspace icon

You can choose a custom icon for your workspace by placing a PNG file named icon.png inside the .idx directory at the same level as your dev.nix file. Firebase Studio will then use this icon to represent your workspace in your dashboard.

Because this file can be checked into source control (such as Git), this is a good way to help everyone who works on your project see the same icon for your project when using Firebase Studio. And because the file can vary across Git branches, you can use this icon to visually distinguish between beta and production app workspaces and for other purposes.

Turn your customizations into a template

To turn your environment configuration into a "starter environment" that anyone can use to build new projects, see the docs for Create custom templates.

Explore all customization options

Check out the dev.nix reference for a detailed description of the environment configuration schema.

Download your files

To download your files as a zip file:

  • Right-click on any directory in the Explorer pane and select Zip and Download.

To download everything in your project directory:

  1. Select File > Open Folder.

  2. Accept the default /home/user directory.

  3. After the files load, right-click your working directory and select Zip and Download. If using the App Prototyping agent, your working directory will be studio. If using a template or uploaded project, this will be your project name.

  4. When prompted to rebuild the environment, click Cancel.

  5. After your download completes, re-open your working directory from the File menu to move back into your workspace.

Use MCP servers

MCP servers provide additional tools and data sources for Gemini to use. For example, you can add the Firebase MCP server to explore your data in Cloud Firestore using natural language while you're building or debugging your application.

Prerequisites

  • If the MCP server requires it, make sure you have a working installation of Node.js and npm.

Choose a compatible MCP server

Firebase Studio has foundational support for MCP servers, which means not all MCP servers are compatible. When choosing an MCP server to add to your Firebase Studio workspace, keep the following in mind:

  • Supported:
    • Standard input/output (stdio) or Server-Sent Events (SSE)/Streamable HTTP transport servers that don't require special forms of authentication
    • Tools provided by MCP servers
  • Currently not supported:
    • Servers that require a graphical user interface or a desktop session
    • Prompts, sampling, or other resources provided by MCP servers

Add an MCP server

  1. From Explorer (Ctrl+Shift+E), edit or create the MCP configuration file.

    • Gemini in Firebase chat uses .idx/mcp.json.

    • Gemini CLI uses .gemini/settings.json.

    If the file doesn't yet exist, create it by right-clicking the parent directory and selecting New file. Create or edit both files to use the MCP server in Gemini in Firebase and Gemini CLI.

  2. Add the server configuration to the content of the file. For example, to add the Firebase MCP server, enter:

    {  "mcpServers": {  "firebase": {  "command": "npx",  "args": [  "-y",  "firebase-tools@latest",  "experimental:mcp"  ]  }  } }

    This configuration file instructs Gemini which MCP server you want it to use. In this example, we've added one server called firebase that will use the npx command to install and run firebase-tools@latest. Other MCP servers require different configurations, but follow the same general format.

  3. In the terminal (Shift+Ctrl+C), run any necessary commands to complete installation. For example, to use the Firebase MCP server, enter the following command to sign in to your account:

    firebase login --no-localhost

    Follow the instructions in the terminal to authorize the session. Some tools require a connected Firebase project. You can use the Firebase MCP server to create a project, or you can run the following command to initialize a Firebase project:

    firebase init

    This creates a firebase.json file in your root directory.

  4. Rebuild your workspace to complete setup:

    1. Open the Command Palette (Shift+Ctrl+P).

    2. Enter Firebase Studio: Rebuild Environment.

Use MCP tools

After installing the MCP server you want to use, the tools or data it provides are available in:

  • Gemini CLI
  • Gemini in Firebase chat when using Agent mode and Agent (Auto-run) modes
  • the App Prototyping agent

For example, if you add the Firebase MCP server, you could ask Gemini to fetch the SDK config for the current project, retrieve data stored in Cloud Firestore and Realtime Database, help you set up Firebase services, and more.

Troubleshoot MCP servers

If an MCP server doesn't work as expected, open your Gemini logs to check for errors:

  1. In the Output (Shift+Ctrl+U), click the drop-down menu and select Gemini.

  2. Check for messages that begin with an [MCPManager] tag. These logs contain information about which MCP servers have been set up, along with any error messages. Use this information to troubleshoot your configuration. When an MCP server connects successfully, you'll see a list of the tools it added.

Try rebuilding your workspace if an MCP server fails to install or connect:

  1. Open the Command Palette (Shift+Ctrl+P).

  2. Enter Firebase Studio: Rebuild Environment.

  3. Wait for your workspace to rebuild, and then try again to use your chosen MCP server.

If the MCP server connects, but Gemini doesn't use the tools it provides:

  • Start a new Gemini chat session.

  • If Gemini can accomplish the task without using an MCP tool, it might attempt a different method. If you want to use a specific tool, try naming the tool in your prompt. For example, you could say "Use firebase_get_sdk_config to get the SDK config for the current project."

  • Join the Google Developer Program.

Next steps