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. 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. 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. 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. 4. Port Models

    Translate Rails ActiveRecord models to Prisma schema. Preserve table names, add indexes that Rails added implicitly, and document any quirks.
  5. 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. 6. Port Views

    Convert ERB templates to React server components. Preserve the URL structure exactly so external links don't break.
  7. 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. 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.