# Firebase Auth to Clerk: export and import migration

## The order

1. Export users with the Firebase CLI auth export. The export includes
   password hashes with Firebase's scrypt parameters and the salt. Keep
   those parameters; they are what the password_hasher declaration needs.
2. Transform into the migration tool's JSON or CSV shape: external_id gets
   the Firebase uid, email_addresses carry email plus verified status,
   displayName and photoURL map to name and image fields, custom claims go
   into public_metadata.
3. Import through the CreateUser backend endpoint declaring the Firebase
   password hasher. Clerk transparently upgrades to bcrypt on first login.
4. Respect the CreateUser rate limit. The migration tool handles pacing and
   error retries; hand-rolled scripts usually learn about the limit the
   hard way.
5. Trial the import on a development instance with a small batch before the
   full run.

## The Firebase-specific traps

- Firebase custom claims are not Clerk session claims. Map them into
  public_metadata, then expose what the app needs via custom session token
  claims as a separate step after migration.
- Phone-auth users: their primary identifier is a phone number, not an
  email. Decide before import whether email or phone is the canonical
  identifier in Clerk, because sign-in flows key off it.
- Anonymous Firebase users cannot migrate. Decide what happens to their
  data (attach to a new account on first real sign-in, or drop it).

## Checklist

- A migrated email/password user signs in with the old password on the
  first attempt.
- Custom claims from Firebase appear in Clerk public_metadata for sampled
  users.
- User count in Firebase matches user count in Clerk, minus the anonymous
  accounts you decided to drop.