firebase-js-sdk Documentation

File: README.md Copy Chapter

Firebase JavaScript SDK

The Firebase JavaScript SDK implements the client-side libraries used by
applications using Firebase services. This SDK is distributed via:

• CDN
• npm package

To get started using Firebase, see
Add Firebase to your JavaScript Project.

Upgrade to Version 9 Copy Chapter

Version 9 has a redesigned API that supports tree-shaking. Read the Upgrade Guide to learn more.

Supported Environments Copy Chapter

Please see Environment Support.

SDK Dev Workflow Copy Chapter

Prerequisites Copy Section

Node.js

Before you can start working on the Firebase JS SDK, you need to have Node.js
installed on your machine. As of July 17th, 2026 the team has been testing with Node.js version
20.19.0, but the required version of Node.js may change as we update our dependencies.

To download Node.js visit https://nodejs.org/en/download/.

NOTE: You can use a tool like NVM
or N to install and manage multiple node versions

Yarn

In addition to Node.js we use yarn to facilitate multi package development.

To install yarn follow the instructions listed on their website:
https://yarnpkg.com/en/docs/install

This repo currently supports building with yarn 1.x. For instance, after installing yarn, run

$ yarn set version 1.22.11

Java

The closure compiler requires a modern Java installation. Java 11+ should be installed: https://www.oracle.com/java/technologies/downloads/#java11

Verify Prerequisites

You can verify your setup by running the following commands in your terminal:

$ node -v
$ yarn -v
$ java -version

Your node version should be 20.19.0 or greater, your yarn version should
be between 1.0.0 and 1.22.11, and your java version should be 11.0 or greater.

NOTE: We will update the documentation as new versions are required, however
for continuing development on the SDK, staying up to date on the stable versions
of these packages is advised

Install Dependencies Copy Section

Once you have Node.js and yarn installed on your machine and have validated
that you are running the proper version, you can set up the development environment
by running the following at the root of the SDK:

$ yarn

Once you have installed all the dependencies, you can build the entire SDK by
running the following command the root of the SDK:

$ yarn build

Testing the SDK Copy Chapter

Test Setup Copy Section

A production project is required to test the Firebase JS SDK. You can create a
new project by visiting the Firebase Console.

Web App Setup

Visit the "Project Overview" and select "Add app" under your project name. Register the app with a
nickname and click through the remaining steps. Without performing this step, you will encounter
the error in the test setup:

FirebaseError: There are no WEB apps associated with this Firebase project

Firestore Database Setup

Visit the "Firestore Database" section of the console and create a Cloud Firestore
database. When prompted to select the set of initial security rules, select
any option (e.g. "Start in Production Mode") since these permission settings
will be overwritten below.

Realtime Database Setup

Visit the "Realtime Database" section of the console and create a realtime
database. When prompted to select the set of initial security rules, select
any option (e.g. "Start in Locked Mode") since these permission settings
will be overwritten below.

Storage Setup

Visit the "Storage" section of the console and create a storage bucket. In
order to run the tests, you will need to update your bucket's CORS rules.

1. Create a new file called cors.json with the contents:

[
    {
        "origin": ["http://localhost:8089"],
        "method": ["GET"],
        "maxAgeSeconds": 3600
    }
]

1. Install gsutil from https://cloud.google.com/storage/docs/gsutil_install
2. You will need to login if this is your first time using gsutil. Run gcloud auth login
   and follow the instructions to login.
3. Run gcloud storage buckets update gs://<your-cloud-storage-bucket> --cors-file=cors.json

For more information, visit https://firebase.google.com/docs/storage/web/download-files#cors_configuration

Then, make sure you have anonymous sign-in provider enabled:

Authentication Support

Visit the authentication config in your project and enable the Anonymous
sign-in provider to complete your project config.

Automated Setup

The tests need to be configured to use the Firebase production project that you
created in the "Test Setup" section above. To do this, run the yarn test:setup
command, as follows:

# Select the Firebase project via the text-based UI. This will run tools/config.js
# and deploy from config/ to your Firebase project.
$ yarn test:setup

# Specify the Firebase project via the command-line arguments.
$ yarn test:setup --projectId=<test_firebase_project_id>

If you see an error like

HTTP Error: 404, Project '<test_firebase_project_id>' does not exist.

then make sure that you have created the database as specified in the "Firestore
Database Setup" section above.

Running the tests Copy Section

Each of the directories in the integration directory as well as the packages
directory have their own test suites. You will need to build the SDK before
running tests. Test suites can be run all together by running the following
command at the root of the package:

$ yarn test

In addition, you can run any of the tests individually by running yarn test in
an individual package directory.

Building the SDK Copy Chapter

Introduction Copy Section

The Firebase JS SDK is built with a series of individual packages that are all
contained in this repository. Development is coordinated via yarn
workspaces and
Lerna (a monorepo management tool).

Each package in the packages directory, constitute a piece of our
implementation. The SDK is built via a combination of all of these packages
which are published under the firebase
scope on NPM.

Testing the SDK Locally Copy Section

Please be sure your product's package has been built before proceeding any further. (If you haven't built this repo before, make sure to run yarn build at the root)
In order to manually test your SDK changes locally, you must use yarn link:

$ cd packages/firebase
$ yarn link # initialize the linking to the other folder
$ cd ../<my-product> # Example: $ cd ../firestore
$ yarn link # link your product to make it available elsewhere
$ cd <my-test-app-dir> # cd into your personal project directory
$ yarn link firebase @firebase/<my-product> # tell yarn to use the locally built firebase SDK instead

This will create a symlink and point your <my-test-app-dir> to the locally built version of the firebase SDK.

Helper Scripts Copy Section

Each package in the packages directory exposes a dev script. This script
will set up a watcher for development on the individual piece of the SDK. In
addition, there is a top level dev script that can be run to start all of the
watch tasks as well as a sandbox server.

You can run the dev script by running the following at the root of the package:

$ yarn dev

Prepush Hooks Copy Section

As part of this repo, we use the NPM package husky to
implement git hooks. We leverage the prepush hook to do two things:

• Automated code styling (using prettier)
• Automated LICENSE header insertion

Contributing Copy Chapter

See Contributing for more information on contributing to the Firebase
JavaScript SDK.

File: e2e/README.md Copy Chapter

E2E Tests

This directory is for Firebase E2E tests that are completely independent of the main SDK workspaces. Packages in here should:

• Have a start trigger independent of the main CI PR/push triggers (e.g., manual trigger, repository_dispatch, from an external runner like Kokoro, etc.)

  A common use case might be to clone this repo, cd into the chosen directory under e2e, npm install, and run npm scripts.

• Have a self-contained set of NPM dependencies. They should not depend on the local version of Firebase in the SDK nor assume inherited availability of any packages in the top level package.json of this repo (typescript, firebase, karma, etc.).

See the template/ directory for an example.

File: integration/firestore/README.md Copy Chapter

These tests are intended to be run against the minified compiled version of the
firebase binary (i.e. firebase.js and firebase-firestore.js of the firebase
package).

The integration test files are modified to replace references to the
firebase_export entrypoint with the following declare statement:

declare var firebase;

This will help the test files pass the compile step, and will allow us to, at
test time, inject the firebase variable into global scope (from the compiled)
files, which will be used by the tests.

File: packages/webchannel-wrapper/README.md Copy Chapter

@firebase/webchannel-wrapper

NOTE: This is specifically tailored for Firebase JS SDK usage, if you are not a member of the Firebase team, please avoid using this package

This is a wrapper of some Webchannel Features for the Firebase JS SDK.

Usage Copy Chapter

The following 5 modules are exposed for use:

• createWebChannelTransport
• ErrorCode
• EventType
• WebChannel
• XhrIoPool

You can include these by doing the following:

ES Modules

import { WebChannel } from '@firebase/webchannel-wrapper'

// Do stuff with WebChannel

CommonJS Modules

const webchannelWrapper = require('@firebase/webchannel-wrapper');

// Do stuff with webchannelWrapper.ErrorCode, webchannelWrapper.EventType, etc

File: packages/util/README.md Copy Chapter

@firebase/util

NOTE: This is specifically tailored for Firebase JS SDK usage, if you are not a
member of the Firebase team, please avoid using this package

This is a wrapper of some Webchannel Features for the Firebase JS SDK.

Usage Copy Chapter

ES Modules

import { Deferred } from '@firebase/util';

// Do stuff with Deferred or any of the other Utils you import

CommonJS Modules

const utils = require('@firebase/util');

// Do stuff with any of the re-exported `utils`

File: packages/template-types/README.md Copy Chapter

@firebase/template-types

This package is not intended for direct usage, and should only be used via the officially supported firebase package.

File: packages/template/README.md Copy Chapter

@firebase/template

This package can be used as a template for anyone creating new packages in the
Firebase JS SDK. It will give you a couple things OOTB:

• TypeScript Support: Your code should be written in TS to be consistent
  with the rest of the SDK.
• Isomorphic Testing/Coverage: Your tests will be run in both Node.js and
  Browser environments and coverage from both, collected.

File: packages/storage-types/README.md Copy Chapter

@firebase/storage-types

This package is not intended for direct usage, and should only be used via the officially supported firebase package.

File: packages/storage-compat/README.md Copy Chapter

@firebase/storage

This is the Cloud Storage component of the Firebase JS SDK.

This package is not intended for direct usage, and should only be used via the officially supported firebase package.