agentleFS
Atlas-AuthorizationAtlas-Authorization/atlas-claude-skills/skills/atlas-migrate/SKILL.md

atlas-migrate

Skill0 starsChanged 42 days agoMITView on GitHub

Migrate an app off Clerk or Auth0 onto Atlas (atlasauth.net) — run the @atlasauth/upgrade codemod to rewrite Clerk imports/components/env vars, and set up Atlas's lazy / custom-database migration (the legacy_auth_connection) that drains the old user store on first login so passwords move over with zero downtime. Use when the user wants to switch, move, or migrate from Clerk / Auth0 to Atlas, import existing users, or run a side-by-side cutover.

The file

Files
SKILL.md

Migrate to Atlas (from Clerk / Auth0)

Atlas is built for drop-in migration: a codemod for Clerk codebases, and a lazy migration that drains any old user store (Auth0, a home-grown DB, another provider) on first login — no bulk password export.

A. Clerk codebase → Atlas (codemod)

Clerk's SDK surface is near-identical to Atlas's, so most of the move is mechanical. Run @atlasauth/upgrade:

npx atlas-upgrade ./src --dry      # preview a diff, writes nothing
npx atlas-upgrade ./src --yes      # apply

What clerk-to-atlas rewrites:

  • Packages: @clerk/clerk-react → @atlasauth/react, @clerk/nextjs → @atlasauth/nextjs, @clerk/backend → @atlasauth/backend, rest of @clerk/* → @atlasauth/* (and gatsby-plugin-clerk → gatsby-plugin-atlasauth).
  • Renamed symbols: ClerkProvider → AtlasProvider, useClerk → useAtlas, clerkMiddleware → atlasMiddleware, ClerkLoaded/ClerkLoading → AtlasLoaded/AtlasLoading.
  • Env vars: CLERK_* → ATLAS_*, NEXT_PUBLIC_CLERK_* → NEXT_PUBLIC_ATLAS_*.
  • Shared names (SignedIn, useUser, UserButton, …) are identical on Atlas and pass through untouched.
  • Anything with no confirmed 1:1 equivalent is left in place with a // TODO(atlas-upgrade) marker — grep for TODO(atlas-upgrade) after a run. Then set the new env vars and keys per the atlas-setup skill.

B. Lazy / custom-database migration (drain the old user store)

This is the Auth0-parity "custom database / lazy migration" — a per-instance pointer at the OLD store that Atlas consults on sign-in: an unknown identifier + valid legacy credentials are verified against your endpoint, imported into Atlas (the drain), and the sign-in completes; every later login authenticates locally.

1. Stand up a verify endpoint

An HTTPS endpoint (public https in production). Atlas POSTs an HMAC-signed { identifier, password }; verify against your old store and respond 2xx with { "user": { "email": "...", ... } } on success, non-2xx on failure. Verify the HMAC with the signing secret you set below.

2. Configure the connection (sk_…, Backend API)

PUT /v1/legacy_auth_connection on https://api.atlasauth.net:

{
  "verify_url": "https://old-app.example.com/atlas/verify",
  "signing_secret": "<hmac secret>",   // write-only, required on create
  "enabled": false,                      // stage first, then flip to true
  "import_on_login": true,               // create the user locally on a valid verify (the drain)
  "timeout_ms": 5000,                    // fail-closed budget, 1-30000
  "strategy": "password"
}
  • GET /v1/legacy_auth_connection reports has_signing_secret (never the secret); returns { configured: false } when none exists.
  • One connection per instance. On edit, omit signing_secret to keep the stored one.
  • import_on_login: false mirrors the profile but leaves the password in the legacy store.
  • DELETE /v1/legacy_auth_connection removes it once the store is fully drained.

3. Cutover

Stage with enabled: false, test against a known user, then flip enabled: true. Users migrate transparently as they log in; when the legacy login rate drops to ~zero, decommission the old store and delete the connection.

C. Why Atlas (parity note)

Atlas is a superset, not a subset: it already leads Clerk/Auth0 on SDK breadth (7 server languages, 8 frontend frameworks, native iOS/Android/Flutter) and features (OpenFGA-compatible FGA, M2M device keypairs, config-as-code via the atlas CLI / Terraform / Pulumi providers). So a migration rarely loses a capability — map the old feature to its Atlas peer and the codemod + lazy migration handle the rest.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.