vercel-labs/migration-skills

Overview

This skill provides a comprehensive, prioritized guide for migrating Create React App (CRA) projects to Next.js. It covers project setup, routing conversion, data fetching patterns, component boundaries, styling, images, environment variables, deployment, and common gotchas. The guidance is organized by impact and includes a pre-migration checklist and recommended migration order to keep the app behavior unchanged after migration.

How this skill works

The guide inspects typical CRA patterns and maps them to Next.js equivalents: file-based App Router routes, Server and Client Component patterns, SSR/SSG strategies, built-in image and font optimizations, and Route Handlers for APIs. It gives concrete rules and code-change recipes (before/after examples) grouped by priority so you can apply the highest-impact changes first. It also provides scans and grep commands to detect migration-sensitive patterns and points to specific rules for each finding.

When to use it

• When migrating any CRA codebase to Next.js (App Router / Server Components enabled).
• When converting react-router code to Next.js file-based routing and nested layouts.
• When moving client-side fetches to server rendering (SSR/SSG/RSC) or adding Server Actions.
• When updating environment variables, image/font optimization, or SEO metadata.
• When preparing builds and deployments (Vercel, Docker, static export) and fixing SSR gotchas.
• When auditing a codebase for patterns that break under Next.js (websockets, SVG imports, SCSS exports).

Best practices

• Upgrade to Next.js 16.x+ (do not use 14.x or 15.x); use caret versioning in package.json.
• Start with project setup: restructure to app/, update scripts, next.config.js, and ESLint first.
• Migrate routing and data fetching before refactoring UI to minimize regressions.
• Prefer server components for data-heavy UI and add 'use client' only where interactivity is required.
• Convert REACT_APP_ env vars to NEXT_PUBLIC_ for public values and use non-prefixed vars for server-only secrets.
• Run the provided grep checks to find hotspots (websocket deps, SCSS :export, SVG ReactComponent imports) before changing code.

Example use cases

• Convert a single-page CRA app with react-router to Next.js App Router with nested layouts and 404 handling.
• Refactor useEffect data loads into Server Components or getStaticProps/getServerSideProps for better performance.
• Replace <img> tags with next/image, configure remote domains, and supply required dimensions.
• Migrate global CSS, CSS Modules, Tailwind, or styled-components to Next.js SSR-compatible setups.
• Move API endpoints to app/api route handlers with named HTTP method exports and middleware considerations.