Cra To Next Migration
Migrate a Create React App codebase to Next.js 16+ with file-based routing, Server Components, and deployment-ready env patterns without changing end-user behavior.
Overview
CRA to Next Migration is an agent skill most often used in Build (also Ship perf, Operate iterate) that walks through 148 rules across 17 categories to move Create React App to Next.js 16+ while preserving behavior.
Install
npx skills add https://github.com/vercel-labs/migration-skills --skill cra-to-next-migrationWhat is this skill?
- 148 prioritized migration rules grouped across 17 categories
- Mandatory Next.js 16.x+ policy—explicitly excludes Next 14 and 15
- Covers React Router → file-based routing, Server Components, SSR/SSG, env vars, images, and fonts
- Success criterion: post-migration app behaves the same for users as pre-migration
- Includes version check workflow via npm info next before pinning dependencies
- 148 migration rules
- 17 rule categories
- Next.js minimum ^16.0.0
Adoption & trust: 420 installs on skills.sh; 11 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your CRA app is hitting scaling, routing, and rendering limits but a full Next.js rewrite feels like an unbounded refactor with easy regressions.
Who is it for?
Solo developers with an existing CRA production app ready to adopt App Router, SSR/SSG, and Next built-in optimizations in one focused migration sprint.
Skip if: Greenfield projects choosing a framework from scratch, or teams committed to staying on CRA with only minor tweaks.
When should I use this skill?
Migrating a CRA app, converting React Router to file-based routing, or adopting Next.js patterns like Server Components, App Router, or image optimization.
What do I get? / Deliverables
You get an ordered migration checklist applied across routing, components, data, styling, and config so the rebuilt Next app matches prior user-visible behavior and targets Next 16+.
- Next.js 16+ project structure with App Router
- Migrated routes and data-fetch patterns
- Updated env and asset optimization configuration
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
CRA→Next is canonical on Build’s frontend shelf because it is a large structural refactor of the product UI layer; secondary Ship coverage reflects testing and perf checks implied by SSR/SSG adoption. Frontend captures React Router removal, App Router layout, image/font optimization, and styling moves—the core migration surface—not backend-only API rewrites unless paired separately.
Where it fits
Convert client-only CRA routes into App Router segments while preserving deep links and layout nesting.
Remap REACT_APP_* style env usage to Next public and server env conventions before deploy.
Apply image and font optimization rules after migration to measure LCP gains versus the old CRA bundle.
Incrementally adopt Server Components in hot paths using the guide’s component-category rules without a second big-bang rewrite.
How it compares
Use instead of scattered blog posts or one-shot chat refactors when you need a numbered rule catalog tuned to CRA-specific pitfalls.
Common Questions / FAQ
Who is cra-to-next-migration for?
Indie builders and small teams maintaining Create React App codebases who want agent-assisted, stepwise conversion to Next.js without relearning everything from forums.
When should I use cra-to-next-migration?
During Build when migrating CRA, converting React Router to file-based routes, adopting Server Components, switching to SSR/SSG, or retooling env vars and image optimization; during Ship when validating perf after the cutover.
Is cra-to-next-migration safe to install?
It is MIT-licensed community guidance—review Security Audits on this page and run your own tests; migration skills drive broad filesystem edits that should go through git and CI.
SKILL.md
READMESKILL.md - Cra To Next Migration
# CRA to Next.js Migration Guide Comprehensive migration guide for converting Create React App projects to Next.js, covering routing, data fetching, components, styling, and deployment. Contains 148 rules across 17 categories, prioritized by migration impact. After a successful migration the application should work the same as it did before the migration. ## When to Apply Reference these guidelines when: - Migrating an existing CRA application to Next.js - Converting React Router routes to file-based routing - Adopting Server Components in a client-heavy app - Moving from client-side rendering to SSR/SSG - Updating environment variables for Next.js - Optimizing images and fonts with Next.js built-ins ## Version Policy **Use Next.js 16.x or later. Do NOT use Next.js 14.x or 15.x.** Before starting migration, check the current latest version: ```bash npm info next version ``` Use the latest version in your package.json with a caret for minor/patch updates. The minimum supported version for this migration guide is `^16.0.0`. ## Rule Categories by Priority | Priority | Category | Impact | Prefix | Rules | | -------- | --------------------- | -------- | --------------- | ----- | | 1 | Project Setup | CRITICAL | `setup-` | 6 | | 2 | Dependencies | CRITICAL | `deps-` | 1 | | 3 | Routing | CRITICAL | `routing-` | 17 | | 4 | Data Fetching | CRITICAL | `data-` | 11 | | 5 | Components | HIGH | `components-` | 9 | | 6 | Environment Variables | HIGH | `env-` | 6 | | 7 | Styling | HIGH | `styling-` | 12 | | 8 | Public Assets | MEDIUM | `assets-` | 5 | | 9 | Images | MEDIUM | `images-` | 8 | | 10 | Fonts | MEDIUM | `fonts-` | 6 | | 11 | SEO & Metadata | MEDIUM | `seo-` | 9 | | 12 | API Routes | MEDIUM | `api-` | 9 | | 13 | State Management | MEDIUM | `state-` | 8 | | 14 | Integrations | MEDIUM | `integrations-` | 1 | | 15 | Testing | LOW | `testing-` | 9 | | 16 | Build & Deploy | LOW | `build-` | 7 | | 17 | Common Gotchas | HIGH | `gotchas-` | 24 | ## Quick Reference ### 1. Project Setup (CRITICAL) - `setup-initial-structure` - Convert CRA folder structure to Next.js App Router - `setup-package-json` - Update dependencies and scripts - `setup-next-config` - Create and configure next.config.js - `setup-typescript` - Migrate TypeScript configuration - `setup-eslint` - Update ESLint for Next.js - `setup-gitignore` - Update .gitignore for Next.js ### 2. Dependencies (CRITICAL) - `deps-react19-compatibility` - Upgrade dependencies for React 19 compatibility ### 3. Routing (CRITICAL) - `routing-basic-pages` - Convert components to file-based routes - `routing-dynamic-routes` - Use [param] syntax for dynamic segments - `routing-catch-all-routes` - Use [...slug] for catch-all routes - `routing-optional-catch-all` - Use [[...slug]] for optional catch-all - `routing-route-groups` - Use (group) folders for organization - `routing-parallel-routes` - Use @slot for parallel routes - `routing-intercepting-routes` - Use (..) for intercepting routes - `routing-link-component` - Replace react-router Link with next/link - `routing-programmatic-navigation` - Replace useNavigate with useRouter - `ro