Understand Firebase for Web

As you're developing a Web app using Firebase, you might encounter unfamiliar concepts, or areas where you need more information to make the right decisions for your project. This page aims to answer those questions or point you to resources to learn more.

If you have questions about a topic not covered on this page, visit one of our online communities. We'll also update this page with new topics periodically, so check back to see if we've added the topic you want to learn about.

SDK versions: namespaced and modular

Firebase provides two API surfaces for Web apps:

  • JavaScript - namespaced. This is the JavaScript interface that Firebase maintained for many years and is familiar to Web developers with older Firebase apps. Because the namespaced API does not benefit from ongoing new feature support, most new apps should instead adopt the modular API.
  • JavaScript - modular. This SDK is based on a modular approach that provides reduced SDK size and greater efficiency with modern JavaScript build tools such as webpack or Rollup.

The modular API integrates well with build tools that strip out code that isn't being used in your app, a process known as "tree-shaking." Apps built with this SDK benefit from greatly reduced size footprints. The namespaced API, though available as a module, does not have a strictly modular structure and does not provide the same degree of size reduction.

Though the majority of the modular API follows the same patterns as the namespaced API, the organization of the code is different. Generally, the namespaced API is oriented towards a namespace and service pattern, while the modular API is oriented toward discrete functions. For example, the namespaced API's dot-chaining, such as firebaseApp.auth(), is replaced in the modular API by a single getAuth() function that takes firebaseApp and returns an Authentication instance.

This means that Web apps created with the namespaced API require refactoring in order to take advantage of modular app design. See the upgrade guide for further details.

JavaScript - modular API for new apps

If you're starting on a new integration with Firebase, you can opt into the modular API when you add and initialize the SDK.

As you develop your app, keep in mind that your code will be organized principally around functions. In the modular API, services are passed as the first argument, and the function then uses the details of the service to do the rest. For example:

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

For more examples and details, see the guides for each product area as well as the the modular API reference documentation.

Ways to add the Web SDKs to your app

Firebase provides JavaScript libraries for most Firebase products, including Remote Config, FCM, and more. How you add Firebase SDKs to your Web app depends on what tooling you're using with your app (like a module bundler).

You can add any of the available libraries to your app via one of the supported methods:

  • npm (for module bundlers)
  • CDN (content delivery network)

For detailed setup instructions, see Add Firebase to your JavaScript App. The rest of this section contains information to help you choose from the available options.

npm

Downloading the Firebase npm package (which includes both browser and Node.js bundles) provides you with a local copy of the Firebase SDK, which may be needed for non-browser applications such as Node.js apps, React Native, or Electron. The download includes Node.js and React Native bundles as an option for some packages. The Node.js bundles are necessary for the server-side rendering (SSR) step of SSR frameworks.

Using npm with a module bundler such as webpack or Rollup provides optimization options to "tree-shake" unused code and apply targeted polyfills, which can greatly reduce the size footprint of your app. Implementing these features may add some complexity to your configuration and build chain, but various mainstream CLI tools can help mitigate that. These tools include Angular, React, Vue, Next, and others.

In summary:

  • Provides valuable app size optimization
  • Robust tooling is available to manage modules
  • Required for SSR with Node.js

CDN (content delivery network)

Adding libraries that are stored on Firebase's CDN is a simple SDK setup method that may be familiar to many developers. Using the CDN to add the SDKs, you won't need a build tool, and your build chain may tend to be simpler and easier to work with compared to module bundlers. If you're not especially concerned about the installed size of your app and don't have special requirements such as transpiling from TypeScript, then CDN could be a good choice.

In summary:

  • Familiar and simple
  • Appropriate when app size is not a major concern
  • Appropriate when your website does not use build tools.

Firebase Web SDK variants

Firebase's Web SDK can be used in both browser and Node applications. However, several products are not available in Node environments. See the list of supported environments.

Some product SDKs provide separate browser and Node variants, each of which are provided in both ESM and CJS formats, and some product SDKs even provide Cordova or React Native variants. The Web SDK is configured to provide the correct variant based on your tooling config or environment and should not require manual selection in most cases. All SDK variants are designed to help build web apps or client apps for end-user access, such as in a Node.js desktop or IoT application. If your goal is to set up administrative access from privileged environments (such as servers) use the Firebase Admin SDK instead.

Environment detection with bundlers and frameworks

When you install the Firebase Web SDK using npm, the JavaScript and Node.js versions are both installed. The package provides detailed environment detection to enable the right bundles for your application.

If your code uses Node.js require statements, the SDK finds the Node-specific bundle. Otherwise, your bundler's settings must be correctly figured to detect the right entry point field in your package.json file (for example, main, browser, or module). If you experience runtime errors with the SDK, check to make sure your bundler is configured to prioritize the correct type of bundle for your environment.

Learn about the Firebase config object

To initialize Firebase in your app, you need to provide your app's Firebase project configuration. You can obtain your Firebase config object at any time.

  • We do not recommend manually editing your config object, especially the following required "Firebase options": apiKey, projectId, and appID. If you initialize your app with invalid or missing values for these required "Firebase options", users of your app may experience serious issues. The exception to this is the authDomain, which can be updated following Best practices for using signInWithRedirect.

  • If you enabled Google Analytics in your Firebase project, your config object contains the field measurementId. Learn more about this field in the Analytics getting started page.

  • If you enable Google Analytics or Realtime Database after you create your Firebase Web App, make sure that the Firebase config object that you use in your app is updated with the associated config values (measurementId and databaseURL, respectively). You can obtain your Firebase config object at any time.

Here's the format of a config object with all services enabled (these values are automatically populated):

var firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  // The value of `databaseURL` depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.appspot.com",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  // For Firebase JavaScript SDK v7.20.0 and later, `measurementId` is an optional field
  measurementId: "G-MEASUREMENT_ID",
};

Available libraries

Additional setup options

Delay loading of Firebase SDKs (from CDN)

You can delay the inclusion of the Firebase SDKs until the entire page has loaded. If you are using modular API CDN scripts with <script type="module">, this is the default behavior. If you are using namespaced CDN scripts as a module, complete these steps to defer loading:

  1. Add a defer flag to each script tag for the Firebase SDKs, then defer the initialization of Firebase using a second script, for example:

    <script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js"></script>

<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-auth.js"></script>
<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-firestore.js"></script>

// ...

<script defer src="./init-firebase.js"></script>

  2. Create an init-firebase.js file, then include the following in the file:

    // TODO: Replace the following with your app's Firebase project configuration
var firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

Use multiple Firebase projects in a single app

In most cases, you only have to initialize Firebase in a single, default app. You can access Firebase from that app in two equivalent ways:

Web

import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a "default" Firebase project
const defaultProject = initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = getStorage(defaultProject);
let defaultFirestore = getFirestore(defaultProject);

// Option 2: Access Firebase services using shorthand notation
defaultStorage = getStorage();
defaultFirestore = getFirestore();
app_default_init_options.js

Web

// Initialize Firebase with a "default" Firebase project
const defaultProject = firebase.initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = defaultProject.storage();
let defaultFirestore = defaultProject.firestore();

// Option 2: Access Firebase services using shorthand notation
defaultStorage = firebase.storage();
defaultFirestore = firebase.firestore();
firebaseapp.js

Sometimes, though, you need to access multiple Firebase projects at the same time. For example, you might want to read data from the database of one Firebase project but store files in a different Firebase project. Or you might want to authenticate one project while keeping a second project unauthenticated.

The Firebase JavaScript SDK allows you to initialize and use multiple Firebase projects in a single app at the same time, with each project using its own Firebase configuration information.

Web

import { initializeApp, getApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a default Firebase project
initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = initializeApp(otherProjectFirebaseConfig, "other");

console.log(getApp().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = getStorage();
const defaultFirestore = getFirestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = getStorage(otherProject);
const otherFirestore = getFirestore(otherProject);
app_multi_project_init_options.js

Web

// Initialize Firebase with a default Firebase project
firebase.initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = firebase.initializeApp(otherProjectFirebaseConfig, "other");

console.log(firebase.app().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = firebase.storage();
const defaultFirestore = firebase.firestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = otherProject.storage();
const otherFirestore = otherProject.firestore();
firebaseapp.js

Run a local web server for development

If you're building a web app, some parts of the Firebase JavaScript SDK require that you serve your web app from a server rather than from the local filesystem. You can use the Firebase CLI to run a local server.

If you already set up Firebase Hosting for your app, you might have already completed several of the steps below.

To serve your web app, you'll use the Firebase CLI, a command-line tool.

  1. Visit the Firebase CLI documentation to learn how to install the CLI or update to its latest version.

  2. Initialize your Firebase project. Run the following command from the root of your local app directory:

    firebase init

  3. Start the local server for development. Run the following command from the root of your local app directory:

    firebase serve

Open source resources for Firebase JavaScript SDKs

Firebase supports open source development, and we encourage community contributions and feedback.

Firebase JavaScript SDKs

Most Firebase JavaScript SDKs are developed as open source libraries in our public Firebase GitHub repository.

Quickstart samples

Firebase maintains a collection of quickstart samples for most Firebase APIs on Web. Find these quickstarts in our public Firebase GitHub quickstart repository. You can use these quickstarts as example code for using Firebase SDKs.