Upgrade your Web / Node.js app from Firebase.com

This document guides you through upgrading your existing web and Node.js apps from Firebase.com to the new Firebase console and 3.x SDKs.

There are three steps to take:

  1. Import your project into the new Firebase console
  2. Update your database code
  3. Update your authentication code

You can import your project at any time. Your applications and the existing SDKs will continue to work. You can then update your code when you are ready to use some of the new Firebase features in your application.

Import your project to the Firebase console

  • Go to the Firebase console and find your project under "Projects currently at Firebase.com".
  • Click Import for the project you're looking to upgrade.
    • If your project is on a paid plan on firebase.com, you will need to set up the billing for the project in the new console. Your billing information is not automatically migrated
    • Select or create a billing account. After importing, this account is responsible for all charges for the project.
  • Your Realtime Database and Hosting content are automatically and instantly imported to the Firebase console.
  • Your user data is automatically migrated to the new authentication backend. This happens in the background and your users can continue to use the app while the data is being migrated. User signups and logins will not be affected. While the system is migrating user accounts, you will see a spinner in the Auth tab of the Firebase console.
  • If you have an active promo code for a Firebase.com app, reach out to us.

Upgrade your Firebase CLI

To use the Command Line Interface with an upgraded project, you'll need to install version 3.0 or later. You can do this by running:

npm install -g firebase-tools

Once you have the latest version of the Firebase CLI, you will need to re-authenticate by running firebase login. To get a new token for continuous integration servers or other headless systems, run firebase login:ci.

Finally, you'll need to run firebase tools:migrate in each of the project directories for your migrated Firebase.com projects.

Update your client version

You don't have to update the code of your applications right away. Existing database and authentication code will continue to work against your upgraded project. But when you are ready to start using some of the new Firebase features in your application, here are the steps to migrate the database code to the new APIs.

The easiest way to get started is to change your script include:

BEFORE
<script src="https://cdn.firebase.com/js/client/2.3.2/firebase.js"></script>
AFTER
<script src="https://www.gstatic.com/firebasejs/4.6.1/firebase.js"></script>

If you are migrating a Node.js app, you can download the latest version of the firebase npm package with the following commands (to ensure firebase is not pinned to the 2.X version, you can uninstall it before installing the latest version):

$ npm uninstall firebase --save
$ npm install firebase --save

Get a database reference

In the new SDKs, you no longer instantiate a database references via new Firebase. Instead, you will initialize the SDK via firebase.initializeApp():

BEFORE
var ref = new Firebase("https://databaseName.firebaseio.com");
AFTER
// See https://firebase.google.com/docs/web/setup#project_setup for how to
// auto-generate this config
var config = {
  apiKey: "apiKey",
  authDomain: "projectId.firebaseapp.com",
  databaseURL: "https://databaseName.firebaseio.com"
};

firebase.initializeApp(config);

var rootRef = firebase.database().ref();

You can auto-generate the config above by following the instructions in the web setup page.

No-argument getters are now read-only properties

Many no-argument getters have been changed to read-only properties:

BEFORE
// Reference
var key = ref.key();
var rootRef = ref.root();
var parentRef = ref.parent();

// Query
var queryRef = query.ref();

// DataSnapshot
ref.on("value", function(snapshot) {
  var dataRef = snapshot.ref();
  var dataKey = snapshot.key();
});
AFTER
// Reference
var key = ref.key;
var rootRef = ref.root;
var parentRef = ref.parent;

// Query
var queryRef = query.ref;

// DataSnapshot
ref.on("value", function(snapshot) {
  var dataRef = snapshot.ref;
  var dataKey = snapshot.key;
});

Update your authentication code

Firebase Authentication functionality now lives behind its own firebase.auth() service and many methods have been renamed. For example, here is how you authenticate a user with an OAuth provider:

BEFORE
ref.authWithOAuthPopup("twitter", function(error, authData) {
  if (error) {
    // An error occurred
    console.error(error);
  } else {
    // User signed in!
    var uid = authData.uid;
  }
});
AFTER
var auth = firebase.auth();

var provider = new firebase.auth.TwitterAuthProvider();
auth.signInWithPopup(provider).then(function(result) {
  // User signed in!
  var uid = result.user.uid;
}).catch(function(error) {
  // An error occurred
});

And here is how signing in with a custom token works both in the 2.x API and in the new API:

BEFORE
ref.authWithCustomToken(AUTH_TOKEN, function(error, authData) {
  if (error) {
    console.log("Login Failed!", error);
  } else {
    console.log("Login Succeeded!", authData);
  }
});
AFTER
firebase.auth().signInWithCustomToken(AUTH_TOKEN).catch(function(error) {
  // Handle Errors here.
  var errorCode = error.code;
  var errorMessage = error.message;
  // ...
});

The custom tokens you generate on your server have a new format. You can use the Firebase Admin SDKs for Node.js and Java to create custom tokens that are compatible with the new API, or you can create custom tokens using a third-party JWT library.

Note that the Firebase Admin SDKs generate custom tokens that expire after one hour, unlike the helper libraries for the 2.x API, which by default generate tokens that expire after 24 hours.

See the auth API references for both web and Node.js for a full list of available methods.

Get the access token

With the Firebase.com Authentication API, you can easily use the provider's access token to call out to the provider's API and get additional information. This access token is still available, but only immediately after the sign-in action has completed.

BEFORE
ref.onAuth(function(authData) {
  if (authData) {
    var accessToken = authData.providerData[authData.provider].accessToken;
  }
})
AFTER
var auth = firebase.auth();

var provider = new firebase.auth.GoogleAuthProvider();
auth.signInWithPopup(provider).then(function(result) {
  var accessToken = result.credential.accessToken;
});

Since Firebase Authentication no longer persists the access token, your application will have to do so itself, if needed.

Monitor authentication state

The method name and callback argument for monitoring authentication state have slightly changed:

BEFORE
ref.onAuth(function(authData) {
  if (authData) {
    // User signed in!
    var uid = authData.uid;
  } else {
    // User logged out
  }
});
AFTER
var auth = firebase.auth();

auth.onAuthStateChanged(function(user) {
  if (user) {
    // User signed in!
    var uid = user.uid;
  } else {
    // User logged out
  }
});

Migrate existing logins

If users have logged into your app with a legacy SDK, then you'll need a bit of code to keep them signed in with the new SDK. Otherwise, they would have to sign in again. Open source sample code for doing this is provided in the Firebase Auth Migration Helpers GitHub repo.

Update the new password reset template

If your app allows users to sign-in with sign-in with Email & Password authentication , you probably also give these users the option to reset their password.

Once you've upgraded to the new SDK, those password reset emails will use the new templates specified in the Firebase Console. Be sure to update them for the needs of your app.

Update your Firebase libraries

If you're using any of the following libraries, you'll need to upgrade to the latest version.

Library Supported Version Resource
AngularFire 2.x.x Github
ReactFire 1.x Github
GeoFire 4.1.x Github

Send feedback about...

Need help? Visit our support page.