I built an AI agent that migrates Next.js Pages Router to App Router

Most Next.js teams have a Pages Router → App Router migration sitting in their backlog. It’s mechanical but careful work, and it keeps getting deprioritized. I built migrate-bot to automate it end-to-end, and this post is about how it works under the h…


This content originally appeared on DEV Community and was authored by Garoro0920

Most Next.js teams have a Pages Router → App Router migration sitting in their backlog. It's mechanical but careful work, and it keeps getting deprioritized. I built migrate-bot to automate it end-to-end, and this post is about how it works under the hood.

What the migration actually involves

App Router isn't just "move files to a new folder". The semantic changes:

  • getStaticProps / getServerSideProps → async Server Components
  • getStaticPaths → generateStaticParams
  • next/router → next/navigation (useRouter / usePathname / useSearchParams)
  • next/head → the Metadata API (export const metadata)
  • pages/_app.tsx + pages/_document.tsx → app/layout.tsx
  • API routes: pages/api/x.ts (single handler) → app/api/x/route.ts (export async function GET/POST/...)
  • The pages/ → app/ restructure, including [slug] dynamic routes

Architecture

The whole thing runs serverless + ephemeral:

  • Cloudflare Workers host the API and landing site
  • Cloudflare D1 (SQLite) stores jobs, orders, installations
  • Cloudflare Queues decouple the webhook handler from the migration pipeline (producer/consumer with an idempotency check so retries don't double-charge)
  • Fly.io Machines run the actual migration: one ephemeral VM per job, destroyed at job end (no code retention)
  • Anthropic Claude does the per-file transforms (Sonnet by default, Opus as a one-shot retry fallback)
  • Stripe for payment, Resend for transactional email

The pipeline as a state machine 

queued → analyzing → planning → migrating → verifying → pr_ready
                                                ↓ (on failure)
                          aborted_blocker → refunding → refunded

Each transition is persisted to D1 so every job is observable, and a mid-pipeline crash transitions to aborted_blocker → automatic refund rather than leaving the customer charged for nothing.

A subtle bug: _document.tsx

Early on, every repo with a pages/_document.tsx failed. The planner maps both _app.tsx and _document.tsx to the same target (app/layout.tsx), and my migrate step recorded the second one as a "failed task" when it detected the target was already written. The pipeline treated any failed task as fatal — so the whole migration aborted.

The fix was to distinguish intentional skips (planned target collisions) from real failures (the LLM aborting or erroring). I added a skippedTaskIds field separate from failedTaskIds, and surfaced the skip in the PR description so the customer knows to manually merge any custom <Html> attributes from their _document.tsx.

Trust model

Since this rewrites real production code, the trust mechanisms matter:

  • The output is always a draft PR — your CI runs first, you review, you merge. Nothing is auto-merged.
  • 14-day full refund if the verify step (typecheck + next build) can't pass for reasons attributable to the service.
  • Code is processed only on an isolated VM and is never used to train any model.

Try it / feedback

It's live at migrate-bot.dev. Pricing is per-repo by file count ($99 / $249 / $499). I'd genuinely value feedback on the approach — especially the pricing shape and the draft-PR + refund trust model.

(Currently not offered to EEA/UK/Switzerland residents due to GDPR territorial scope; revisiting post-launch.)


This content originally appeared on DEV Community and was authored by Garoro0920


Print Share Comment Cite Upload Translate Updates
APA

Garoro0920 | Sciencx (2026-05-25T14:36:24+00:00) I built an AI agent that migrates Next.js Pages Router to App Router. Retrieved from https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/

MLA
" » I built an AI agent that migrates Next.js Pages Router to App Router." Garoro0920 | Sciencx - Monday May 25, 2026, https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/
HARVARD
Garoro0920 | Sciencx Monday May 25, 2026 » I built an AI agent that migrates Next.js Pages Router to App Router., viewed ,<https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/>
VANCOUVER
Garoro0920 | Sciencx - » I built an AI agent that migrates Next.js Pages Router to App Router. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/
CHICAGO
" » I built an AI agent that migrates Next.js Pages Router to App Router." Garoro0920 | Sciencx - Accessed . https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/
IEEE
" » I built an AI agent that migrates Next.js Pages Router to App Router." Garoro0920 | Sciencx [Online]. Available: https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/. [Accessed: ]
rf:citation
» I built an AI agent that migrates Next.js Pages Router to App Router | Garoro0920 | Sciencx | https://www.scien.cx/2026/05/25/i-built-an-ai-agent-that-migrates-next-js-pages-router-to-app-router/ |

Please log in to upload a file.



There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Related Posts