Migrate from Firebase

Learn how to migrate your user base from Firebase to Clerk.

Overview

Migrating your user base from Firebase to Clerk is a 2-part process that can be accomplished with just a few steps.

The first part involves using the Firebase CLI to export your existing user base from Firebase.

The second part is about writing a script to loop through your users and add each and everyone to your Clerk application.

Also, this guide assumes you already created a Clerk application. If you didn't, you can easily create a new one in the Clerk Dashboard.

Exporting from Firebase

For this step, you'll need the Firebase CLI. You can install it in a number of different ways, and in this guide, we'll do it through the npm CLI.

npm install -g firebase-tools

Once the installation finishes, you are ready to communicate with Firebase through the terminal.

But before you can do anything, Firebase needs to know who you are, so go ahead and sign in to your Firebase account through the CLI.

firebase login

Now, find the Project ID of the project you're trying to export from, as this will be needed in the next step.

firebase projects:list

With the project's ID in hand, it's time to export your users, so make sure you're in the directory you want the backup file to be created.

firebase auth:export firebase-users.json --format=json --project <YOUR_PROJECT_ID>

Here's what this command is doing:

firebase auth:export: it tells Firebase you're trying to export the user base.

firebase-users.json: the name of the file you're about to create.

--format=json: make it a JSON file.

--project <YOUR_PROJECT_ID>: it tells Firebase which project you're trying to export from. Don't forget to replace <YOUR_PROJECT_ID> with the Project ID you found in the previous step.

You should now have a JSON file called firebase-users.json (or the name you chose in the last step).

Importing into Clerk

First, you'll need a few values from your Firebase project.

In your Firebase project’s dashboard, navigate to Authentication and click on the 3 vertical dots at the top of the user's list, then click on Password hash parameters.

On the new window that opens, you'll find the following values: base64_signer_key, base64_salt_separator, rounds and mem_cost.

You can find more information about this page and the values above on Firebase's documentation.

Next, create a file named migrate-to-clerk.js and paste the following snippet.

migrate-to-clerk.js1
const fetch = require('node-fetch')
2
const firebaseUsers = require('./firebase-users.json')
3

4
async function migrateToClerk() {
5
    // You can find these values on your Firebase project's authentication settings
6
    const signerKey = ''
7
    const saltSeparator = ''
8
    const rounds = ''
9
    const memoryCost = ''
10

11
		// You can find this value on your Clerk application's dashboard
12
    const clerkBackendApiKey = ''
13

14
    for (let user of firebaseUsers.users) {
15
        const { email, localId, passwordHash, salt } = user
16

17
        const body = passwordHash
18
            ? {
19
                  email_address: [email],
20
                  external_id: localId,
21
                  password_hasher: 'scrypt_firebase',
22
                  password_digest: `${passwordHash}$${salt}$${signerKey}$${saltSeparator}$${rounds}$${memoryCost}`,
23
              }
24
            : {
25
                  email_address: [email],
26
                  external_id: localId,
27
                  skip_password_requirement: true,
28
              }
29

30
        try {
31
            const result = await fetch('https://api.clerk.dev/v1/users', {
32
                method: 'POST',
33
                headers: {
34
                    Authorization: `Bearer ${clerkBackendApiKey}`,
35
                    'Content-Type': 'application/json',
36
                },
37
                body: JSON.stringify(body),
38
            })
39

40
            if (!result.ok) {
41
                throw Error(result.statusText)
42
            } else {
43
                console.log(`${email} added successfully`)
44
            }
45
        } catch (error) {
46
            console.error(`Error migrating ${email}: ${error}`)
47
        }
48
    }
49
}
50

51
migrateToClerk()

Here, body will either hold the necessary information to migrate a password-based user or in the case of an OAuth-based user, it'll skip the password check. It will also have the previous user ID as external_id, so you can link the newly created users with their existing data.

Before we run the script, a few steps are required:

Run npm init -y
Run npm i node-fetch@2
Make sure the firebaseUsers import at the top is pointing to the right directory and filename
Add the values from the previous step in the 4 const empty values
Add your Backend API Key as clerkBackendApiKey
Enable any Social Login provider that might have been used by your users

With everything set, it's time to run the script from the terminal.

node ./migrate-to-clerk.js

And that's it. Once the script has finished running, your user base will be fully migrated to Clerk.

Next steps

If you want to know more about the /users endpoint, you can always read about it in the documentation.

Also, if you need any assistance, make sure to reach out to us.