The leap from Next.js 12 to 15 is one of the most significant upgrades in the framework’s history. It’s not just a version bump but a paradigm shift, introducing the App Router, React 19, and a host of powerful new features. While the task can seem daunting, this upgrade can be completed without a complete rewrite.
This guide outlines a pragmatic, incremental strategy to safely migrate your application. We’ll show you how to stabilize your app on the new version, adopt the App Router one slice at a time, and tackle breaking changes with confidence. Most importantly, we’ll highlight how you can use an AI assistant like Gemini or ChatGPT as your copilot to debug errors, refactor code, and accelerate the entire process.
Let’s get started.
Phase 1: AI-Powered Planning and Preparation
Before changing a single line of code, you need a solid plan and a verifiable baseline.
1. Consult Your AI Copilot for a Custom Migration Plan
Every project is unique. Before you begin, leverage your AI assistant to create a tailored checklist.
- Provide Context: Give your LLM your package.json, next.config.js, and a brief description of your app’s architecture (e.g., “We use Styled Components, Redux, and have a custom server”).
- Ask for a Plan: Use a prompt like, “Based on these files, generate a high-level migration plan for upgrading from Next.js 12 to Next.js 15. Highlight potential conflicts with my dependencies and suggest the correct order of operations.”
This initial step will help you anticipate project-specific challenges right from the start.
The rest of this guide should essentially be coming from your AI tool and you can use the guide to validate against that and make adjustments.
2. Establish Your Baseline: Don’t Migrate Blindly
You can’t know if you’ve succeeded if you don’t know where you started. This baseline is your safety net.
- Performance Metrics: Record your core performance scores using Lighthouse and Web Vitals. Take note of metrics like Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS).
- Visual Snapshots: Use a visual regression testing tool (like Chromatic or Percy) or manually screenshot critical user flows (e.g., authentication, checkout, key dashboards).
- Test Suite: Ensure all your existing tests (unit, integration, E2E) are up-to-date and passing on your main branch.
- Version Control: Commit your work after every single successful step. This makes rollbacks trivial if you hit a dead end.
Phase 2: The Core Upgrade and AI-Powered Debugging
With a safety net in place, it’s time to perform the core dependency upgrade and use AI to rapidly solve the inevitable breaking changes.
3. Upgrade Core Dependencies
The Next.js team provides an official codemod to handle the initial upgrade, which bumps Next.js, React, and related packages.
# Run the official upgrader
npx @next/codemod@canary upgrade latest
# Or, if you prefer, upgrade manually:
npm install next@latest react@latest react-dom@latest eslint-config-next@latest
You will likely encounter peer dependency warnings related to React 19. Follow the official Next.js upgrade guide for any specific instructions.
4. Run Targeted Codemods for Low-Hanging Fruit
Next.js provides several codemods to automate fixes for common breaking changes. Run these early to reduce manual work. Always run with the –dry –print flags first to preview changes.
# v15: Makes request APIs (cookies, headers) async
npx @next/codemod@latest next-async-request-api .
# v15: Renames `experimental-edge` to `edge`
npx @next/codemod@latest app-dir-runtime-config-experimental-edge .
# v13+: Migrates from @next/font to the built-in next/font
npx @next/codemod@latest built-in-next-font .
# If coming from v12, these are essential
npx @next/codemod@latest next-image-to-legacy-image .
npx @next/codemod@latest new-link .
5. AI-Assisted Bug Fixing
After upgrading dependencies and running codemods, your app will likely be broken. This is expected. Your test suite is now your to-do list, and your AI is your debugger.
Your workflow should be:
- Run your build, lint, and tests.
- If you’re using a CLI AI tool like Claude Code or Gemini CLI then you essentially just need to tell your tool to run the build, lint, and tests and as errors pop up tell it to fix it. If you are using a web based LLM then you need to paste the error into your LLM with a prompt like: “I’m upgrading to Next.js 15 and got this error. Explain what breaking change is causing it and provide the corrected code.”
- Apply the fix, commit, and repeat until all errors are resolved and tests pass.
This turns a frustrating debugging session into a methodical, AI-accelerated process for tackling breaking changes.
Phase 3: AI-Assisted App Router Migration
This is where the real work begins. The key is to migrate incrementally, route by route, using your AI to refactor patterns and explain new concepts.
6. AI-Assisted Router Adjustments: Planning
Before creating a single file, consult your AI. You have two options, and the recommended path is to stabilize on Next.js 15 with the Pages Router first. Get all your tests passing with React 18 before you even create the /app directory.
Ask your LLM to explain the pros and cons of migrating to the App Router route-by-route versus stabilizing on Next.js 15 with the Pages Router first. This will help guide you in the right direction and solidify your understanding of the strategy.
7. Creating the Root Layout
The App Router introduces a new file-based layout system.
- Create an /app directory.
- Create app/layout.tsx. This file replaces _app.tsx and _document.tsx for all routes you migrate into /app.
- Your existing _app.tsx and _document.tsx will continue to work for any routes still in the /pages directory.
8. Migrating Your First Route Slice with AI
Start with a simple, low-risk page (like an “About Us” or “Contact” page).
- Create the Server Component: For a page at /about, create a new file at app/about/page.tsx.
- Move the Page Content: Take the component from pages/about.tsx and move it into a new client component file, e.g., components/about-page-client.tsx. Add the ‘use client’ directive at the top.
- Fetch Data: In app/about/page.tsx, perform any data fetching directly within the component (this is now a React Server Component!). Then, import and render your client component, passing the data down as props.
- Update Metadata: Replace any <Head> tags from next/head with the metadata export.
AI Tip: This is a perfect refactoring task for an LLM. Give it the code from pages/about.tsx and say, “Convert this Pages Router component into the new App Router pattern. Create a Server Component for data fetching and a Client Component for the UI. Also, convert the next/head usage to the new metadata API.”
9. Modernizing Data Fetching and APIs with AI
As you migrate each route, you’ll need to map old patterns to their App Router equivalents. This is where an AI can be an invaluable teacher.
- Data Fetching:
- getServerSideProps → fetch() directly in a Server Component.
- getStaticProps / getStaticPaths → Use generateStaticParams for dynamic routes and fetch() for data.
- API Routes:
- /pages/api/* → app/**/route.ts.
- Navigation:
- next/router (useRouter) → next/navigation (useRouter, usePathname, useSearchParams).
Instead of just reading docs, give your AI your old code and ask it to perform the conversion. It will not only give you the answer but can also explain why the new pattern is different.
Phase 4: Finalizing and Optimizing
Once all your routes live in the /app directory, you’re in the home stretch.
10. Harden, Optimize, and Test with Turbopack
With the migration functionally complete, it’s time for performance tuning.
- Review Caching: Double-check that you have explicitly set caching behavior for fetch calls and Route Handlers to avoid performance regressions.
- Audit Packages: Review serverExternalPackages in your next.config.js.
- Enable Turbopack: Test your production build with Turbopack for potentially massive speed improvements in CI/CD.
next build –turbopack
11. Final Cutover
The last step is to remove the legacy scaffolding.
- Delete the /pages directory.
- Remove the _app.tsx and _document.tsx files.
- Run your entire test suite one last time.
- Perform a final accessibility and performance check against your baseline.
Conclusion
Upgrading from Next.js 12 to 15 is a marathon, not a sprint. By following an incremental, test-driven process, you can manage the complexity and avoid risky, all-or-nothing deployments. Create a baseline, lean on codemods, migrate slice by slice, and use your AI assistant as a powerful pair programmer to navigate the new APIs and paradigms.
The payoff is worth it with a faster, more powerful application built on the future of React and Next.js.
