Understand Firebase projects

This page offers brief overviews of several important concepts about Firebase projects. When available, follow the links to find more detailed information about features, services, and even other platforms. At the bottom of this page, find a listing of general best practices for Firebase projects.

Relationship between Firebase projects, apps, and products

A Firebase project is the top-level entity for Firebase. In your project, you can add Firebase apps that can be iOS, Android, or Web apps. After you configure your apps to use Firebase, you can then add the Firebase SDKs for any number of Firebase products, like Analytics, Cloud Firestore, Performance Monitoring, or Remote Config.

Learn more detailed information about this process in the Getting Started guides (iOS | Android | Web | Unity | C++).

Relationship between Firebase projects and Google Cloud Platform (GCP)

When you create a new Firebase project in the Firebase console, you're actually creating a Google Cloud Platform (GCP) project behind the scenes. You can think of a GCP project as a virtual container for data, code, configuration, and services. A Firebase project is a GCP project that has additional Firebase-specific configurations and services. You can even create a GCP project first, then add Firebase to the project later.

Since a Firebase project is a GCP project:

  • Projects that appear in the Firebase console also appear in the GCP console and Google APIs console.

  • Billing and permissions for projects are shared across Firebase and GCP.

  • Unique identifiers for a project (like project ID) are shared across Firebase and GCP.

  • You can use products and APIs from both Firebase and GCP in your project.

  • Deleting a project deletes it across Firebase and GCP.

Setting up a Firebase project and adding apps

You can set up a Firebase project and add apps in the Firebase console (or, for advanced use cases, via the Firebase Management REST API). When you set up a project and add your apps, you need to make several configuration decisions and add special configuration files or objects to your local projects.

Make sure to review some general best practices before setting up your project and adding apps.

The project name

When you create a project, you provide a project name. This identifier is the internal-only name for your project in the Firebase console, the GCP console, and the Firebase CLI. The project name is not exposed in any publicly visible Firebase or GCP product, service, or resource; it simply serves to help you more easily distinguish your various projects.

You can edit your project name at any time in your settings Project settings. Your project name is displayed in the top pane.

The project ID

Your Firebase project (and its associated GCP project) has a project ID which is the globally unique identifier for your project across all of Firebase and GCP. When you create a Firebase project, Firebase automatically assigns a unique ID to your project, but you can edit it during setup.

If you delete a project, the project ID is also deleted and can never be used again by any other project.

Firebase resources and the project ID

The project ID displays in publicly visible Firebase resources, for example:

  • Default Hosting subdomain — projectID.web.app and projectID.firebaseapp.com
  • Default Realtime Database URL — projectID.firebaseio.com
  • Default Cloud Storage bucket name — projectID.appspot.com

For all of the aforementioned resources, you can create non-default instances. The publicly visible names of non-defaults are fully-customizable. You can connect custom domains to your Firebase-hosted site, shard your Realtime Database, and create multiple Cloud Storage buckets (visit your platform's Get Started page).

The Firebase CLI and the project ID

For some use cases, you might have multiple Firebase projects associated with the same local app directory. In these situations, when you use the Firebase CLI, you need to pass the --project flag with your firebase commands to communicate which Firebase project you want to interact with.

You can also set up project aliases for your various Firebase projects so that you don't have to remember project IDs.

API calls and the project ID

For many API calls, you need to include the project ID to identify the Firebase project.

Find your project ID

  • In the Firebase console, click settings, then select Project settings. Your project ID is displayed in the top pane.

  • Using the Firebase CLI, run firebase projects:list. Your project ID is displayed along with all the Firebase projects associated with your account.

Firebase config files and objects

When you add an app to your Firebase project, the Firebase console provides a Firebase configuration file (Android/iOS) or a configuration object (web) that you add directly into your local project.

  • For iOS, you add a GoogleService-Info.plist configuration file
  • For Android, you add a google-services.json configuration file
  • For web, you add a Firebase configuration object for your initialization scripts

At any time, you can obtain your Firebase config files or config object.

A Firebase config file or config object associates your app with your Firebase project and its resources (databases, storage buckets, etc.). The configuration includes "Firebase options", which are parameters required by Firebase and Google services to communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. The required, minimum set of Firebase options is:

  • API key: a simple encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO)
  • Project ID: the unique identifier for your Firebase project across all of Firebase and GCP (example value: myapp-project-123)
  • Application ID ("AppID"): the unique identifier for your Firebase app across all of Firebase with a format that is platform-dependent:
    • For Firebase Android apps: mobilesdk_app_id (example value: 1:1234567890:android:321abc456def7890)
      This is not an Android package name.
    • For Firebase iOS apps: GOOGLE_APP_ID (example value: 1:1234567890:ios:321abc456def7890)
      This is not an Apple Bundle ID.
    • For Firebase Web apps: appId (example value: 1:65211879909:web:3ae38ef1cdcb2e01fe5f0c)

The content of the Firebase config file is considered public, including your platform-specific ID (entered in the Firebase console setup workflow) and values that are specific to your Firebase project, like your API Key, Realtime Database URL, and Storage bucket name. Given this, use security rules to protect your data and files in Realtime Database, Cloud Firestore, and Cloud Storage.

For open source projects, we generally do not recommend including your Firebase config file or config object in source control because, in most cases, your users should create their own Firebase projects and point their apps to their own backends.

Managing a Firebase project

Make sure to review the general project-level best practices for considerations that might affect how you manage your Firebase project.

Tools to manage your project

Firebase console

The Firebase console offers the richest environment for managing Firebase products, apps, and project-level settings.

Firebase console - project overview screen

The left-side panel of the console lists the Firebase products, organized by top-level categories. At the top of the left-side panel, access your project settings by clicking settings (settings include integrations, access permissions, and billing).

The middle of the console displays buttons that launch setup workflows to add various types of apps. After you start using Firebase, the main area of the console changes into a dashboard that displays stats on the products you use.

Firebase CLI (a command line tool)

Firebase also offers the Firebase CLI for configuring and managing specific Firebase products, like Firebase Hosting and Cloud Functions for Firebase.

After installing the CLI using npm, you have access to the global firebase command. Use the CLI to deploy new versions of your Firebase-hosted content or updates to your functions. You can also link your local app directory to your Firebase project using the CLI.

Firebase Management REST API

Using the Firebase Management REST API, you can programmatically manage your Firebase project. For example, you can programmatically add an Android app or an iOS app with your project. You can also list the apps (Android / iOS) that are within your project.

General best practices

Adding apps to a project

Ensure that all apps within a project are platform variants of the same application from an end-user perspective. It's advisable to add the Android, iOS, and web versions of the same app or game to the same Firebase project. All the apps in a project generally share the same Firebase resources (database, storage buckets, etc.).

If you have multiple build variants with different iOS bundle IDs or Android app IDs defined, you can add each variant to a separate Firebase project. However, if you have variants that share the same Firebase resources, add them to the same Firebase project.

While there is no restriction on the number of apps within a project, adding an app can create one or more underlying OAuth 2.0 client IDs. There is a limit of around 30 client IDs that can be created within a single project.

Multi-tenancy

Connecting several different logically independent apps and/or web sites to a single project (often called "multi-tenancy") is not recommended. Multi-tenancy can lead to serious configuration and data privacy concerns problems, including unintended issues with analytics aggregation, shared authentication, overly-complex database structures, and difficulties with security rules.

Generally, if a set of apps don't share the same data and configurations, strongly consider adding each app to a different Firebase project.

For example, if you develop a white label application, each independently labelled app should have its own Firebase project. Each app doesn't, and shouldn't (for privacy reasons), share data with the others.

Note some general limits for Firebase projects, apps, and sites:

  • Number of projects per account

    • Free-tier Spark plan — Your project quota is limited to a small number of projects (usually around 5-10).
    • Paid plans — Your project quota per billing account increases substantially as long as your Cloud billing account is in good standing.

    The limit on project quota is rarely a concern for most developers, but if needed, you can request an increase in your project quota.

    Note that the complete deletion of a project requires 30 days and counts toward your quota until it is fully deleted.

  • Number of apps per project

    While there is no restriction on the number of apps within a project, adding an app can create one or more underlying OAuth 2.0 client IDs. There is a limit of around 30 client IDs that can be created within a single project.

  • Number of hosting sites per project

    The Firebase Hosting multisite feature supports a maximum of 36 sites per project.

Launching your app