Migrate a Rails App to Next.js with Claude Code
End-to-end framework migration playbook. Realistic, opinionated, suitable for a 5-10K LOC app.
Engineering
advanced
480 min
Claude Code
Cursor
GitHub Actions
-
1. Scope Audit
Read this Rails repo and produce a migration audit: list of routes, models, services, view templates, ActiveJob jobs, and external integrations. Flag anything that doesn't have a clean Next/JS equivalent.
-
2. Architecture Plan
Propose the target Next.js 14 architecture: App Router vs Pages Router, server components, API route layout, ORM choice (Prisma/Drizzle), background job runner replacement. Justify each choice.
-
3. DB Migration Strategy
Write a phased database migration plan that allows both Rails and Next to read/write during transition. Identify exact steps for cutover including monitoring and rollback.
-
4. Port Models
Translate Rails ActiveRecord models to Prisma schema. Preserve table names, add indexes that Rails added implicitly, and document any quirks.
-
5. Port Controllers/Routes
For each Rails controller action, generate the equivalent Next.js route handler with input validation, auth, and same response shape.
-
6. Port Views
Convert ERB templates to React server components. Preserve the URL structure exactly so external links don't break.
-
7. Port Background Jobs
Translate ActiveJob jobs to a queue-based runner (BullMQ/QStash). Keep the same job names and arguments for observability continuity.
-
8. Cutover Plan
Produce a deployment sequence with pre-cutover checks, traffic-shift strategy, monitoring, and a rollback path. The cutover must be revertible within 5 minutes.