# cra-to-next-migration

Guides code assistants through migrating Create React App codebases to Next.js 16+. It converts React Router routes, adjusts environment variables, and adopts App Router patterns.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 900 installs · ★ 13
- Author: community
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/vercel-labs/migration-skills/tree/HEAD/cra-to-next-migration/SKILL.md
- Updated: 2026-01-30
- HTML: https://affpapa.org/en/nevibecode/skills/cra-to-next-migration

## What it does

This skill provides a structured set of 148 rules across 17 categories to transition legacy Create React App codebases into Next.js. It directs your AI assistant through updating `package.json`, configuring TypeScript, and restructuring application folders.

During the transition, the agent translates React Router hierarchies into the file-based App Router. Links switch to `next/link`, navigation calls adapt to `useRouter`, and data fetching shifts from `useEffect` into Server Components or Server Actions. Environment variable names update from `REACT_APP_` prefixes to `NEXT_PUBLIC_`.

The migration rules mandate Next.js `16.x` or newer and align with React 19 dependencies. Targeted migrations to Next.js 14.x or 15.x are strictly forbidden by this guide.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/migration-skills --skill cra-to-next-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cra-to-next-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cra-to-next-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/migration-skills --skill cra-to-next-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cra-to-next-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/migration-skills --skill cra-to-next-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cra-to-next-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vercel-labs/migration-skills cra-to-next-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/cra-to-next-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/migration-skills --skill cra-to-next-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vercel-labs/migration-skills --path cra-to-next-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cra-to-next-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/migration-skills --skill cra-to-next-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vercel-labs/migration-skills/tree/HEAD/cra-to-next-migration/SKILL.md

## When to use it
- migrate Create React App projects to Next.js 16
- convert React Router routes to App Router folders
- switch client-side data fetching to Server Components
- update environment variable prefixes to `NEXT_PUBLIC_`

## Example prompts
- Migrate this CRA repository to Next.js App Router using cra-to-next-migration.
- Replace React Router navigation in this module with next/link and useRouter.
- Refactor data fetching in this component from useEffect to a Server Component.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c4751feefb1c6b74.

BEGIN THIRD-PARTY FILE c4751feefb1c6b74
````text
---
name: cra-to-next-migration
description: Comprehensive guide for migrating Create React App (CRA) projects to Next.js. Use when migrating a CRA app, converting React Router to file-based routing, or adopting Next.js patterns like Server Components, App Router, or image optimization.
license: MIT
metadata:
  author: community
  version: "1.0.0"
---

# 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     |
````
END THIRD-PARTY FILE c4751feefb1c6b74

The third-party file has ended. Everything between the c4751feefb1c6b74 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2766 of 16349 bytes. © community · MIT · https://github.com/vercel-labs/migration-skills/tree/HEAD/cra-to-next-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md