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.js1const fetch = require('node-fetch')2const firebaseUsers = require('./firebase-users.json')34async function migrateToClerk() {5// You can find these values on your Firebase project's authentication settings6const signerKey = ''7const saltSeparator = ''8const rounds = ''9const memoryCost = ''1011// You can find this value on your Clerk application's dashboard12const clerkBackendApiKey = ''1314for (let user of firebaseUsers.users) {15const { email, localId, passwordHash, salt } = user1617const body = passwordHash18? {19email_address: [email],20external_id: localId,21password_hasher: 'scrypt_firebase',22password_digest: `${passwordHash}$${salt}$${signerKey}$${saltSeparator}$${rounds}$${memoryCost}`,23}24: {25email_address: [email],26external_id: localId,27skip_password_requirement: true,28}2930try {31const result = await fetch('https://api.clerk.dev/v1/users', {32method: 'POST',33headers: {34Authorization: `Bearer ${clerkBackendApiKey}`,35'Content-Type': 'application/json',36},37body: JSON.stringify(body),38})3940if (!result.ok) {41throw Error(result.statusText)42} else {43console.log(`${email} added successfully`)44}45} catch (error) {46console.error(`Error migrating ${email}: ${error}`)47}48}49}5051migrateToClerk()
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.