Migrate from Firebase

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

Export your Firebase users

Install the Firebase CLI

If you haven't already, install the Firebase CLI:

terminal
npm install -g firebase-tools

Log in to Firebase

terminal
firebase login

Find your Firebase project ID

Use the firebase CLI to list your projects and find the project ID you want to export.

terminal
firebase projects:list

Export your Firebase users using the CLI

Use the firebase CLI to export your users to a JSON file.

terminal
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 that contains all your Firebase users.

Retrieve your password hash parameters

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.

Create a Node script

Now you have all the information you need to import your Firebase users into Clerk. This example uses node, but you can use any other language or method if you so wish.

init npm

terminal
npm init -y

Install dependencies

terminal
npm i node-fetch@2

Create a script

terminal/migrate-to-clerk.js
const fetch = require('node-fetch')
const firebaseUsers = require('./firebase-users.json')
 
async function migrateToClerk() {
    // You can find these values on your Firebase project's authentication settings
    const signerKey = ''
    const saltSeparator = ''
    const rounds = ''
    const memoryCost = ''
 
		// You can find this value on your Clerk application's dashboard
    const clerkBackendApiKey = ''
 
    for (let user of firebaseUsers.users) {
        const { email, localId, passwordHash, salt } = user
 
        const body = passwordHash
            ? {
                  email_address: [email],
                  external_id: localId,
                  password_hasher: 'scrypt_firebase',
                  password_digest: `${passwordHash}$${salt}$${signerKey}$${saltSeparator}$${rounds}$${memoryCost}`,
              }
            : {
                  email_address: [email],
                  external_id: localId,
                  skip_password_requirement: true,
              }
 
        try {
            const result = await fetch('https://api.clerk.dev/v1/users', {
                method: 'POST',
                headers: {
                    Authorization: `Bearer ${clerkBackendApiKey}`,
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify(body),
            })
 
            if (!result.ok) {
                throw Error(result.statusText)
            } else {
                console.log(`${email} added successfully`)
            }
        } catch (error) {
            console.error(`Error migrating ${email}: ${error}`)
        }
    }
}
 
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.

Run the script

terminal
node migrate-to-clerk.js

Note that this implementation does not take rate limiting into account. If you have a large user base, you may want to implement a retry mechanism. Clerk will return a 429 status code if you exceed the rate limit. The current rate limit is 20 requests per 10 seconds.

Once the script has finished running, your user base will be fully migrated to Clerk.

Last updated on October 31, 2023