jikime-migration-to-nextjs

name	jikime-migration-to-nextjs
description	Legacy to Next.js 16 migration workflow specialist. Analyzes legacy projects (Vue, React CRA, Angular, Svelte) and orchestrates migration to modern Next.js 16 App Router architecture. Use when migrating frontend projects to Next.js or asking about framework migration patterns.
argument-hint	["source-path"]
disable-model-invocation	false
user-invocable	false
allowed-tools	Read, Grep, Glob, Edit, Write
context	fork
agent	Explore
version	2.1.0
tags	["migration","nextjs","react","vue","angular","svelte","app-router","cra"]
triggers	{"keywords":["migrate","migration","nextjs","vue-to-react","angular-to-react","cra-to-nextjs","create-react-app","react-scripts","마이그레이션"],"phases":["plan","run"],"agents":["manager-strategy","frontend"],"languages":[]}
progressive_disclosure	{"enabled":true,"level1_tokens":"~100","level2_tokens":"~5500"}

Dynamic Context (auto-loaded)

Current Dependencies

!cat package.json 2>/dev/null | grep -A 30 '"dependencies"' | head -35 || echo "No package.json found"

Framework Detection

!ls -la src/ 2>/dev/null | head -10 || ls -la . 2>/dev/null | grep -E "\.(vue|tsx|jsx|svelte|component\.ts)$" | head -10 || echo "No source files detected"

Migration Config

!cat .migrate-config.yaml 2>/dev/null | head -20 || echo "No migration config found"

---

Overview

This skill provides a comprehensive workflow for migrating legacy frontend projects to Next.js 16 with App Router.

Target Stack

Technology	Version	Purpose
Framework	Next.js 16	App Router architecture
Language	TypeScript 5.x	Type safety
Styling	Tailwind CSS 4.x	Utility-first CSS
UI Components	shadcn/ui	Accessible components
Icons	lucide-react	Icon library
State	Zustand	State management
Database ORM	Prisma / Drizzle	Data access layer

Supported Source Frameworks

Framework	Versions	Detection Pattern
Vue.js	2.x, 3.x	vue in package.json, .vue files
React CRA	16+, 17+, 18+	react-scripts in package.json
React Vite	All	@vitejs/plugin-react in vite.config
Angular	12+ ~ 17+	@angular/core in package.json
Svelte	3.x, 4.x	svelte in package.json

---

Migration Workflow

/jikime:migrate-1-analyze "./my-vue-app"
    │
    └─▶ ./migrations/my-vue-app/as_is_spec.md
                │
/jikime:migrate-2-plan my-vue-app
                │
                └─▶ ./migrations/my-vue-app/migration_plan.md
                            │
/jikime:migrate-2-plan --skill my-vue-app
                            │
                            └─▶ .claude/skills/my-vue-app/SKILL.md
                                        │
/jikime:migrate-3-execute my-vue-app [--output ./out]
                                        │
                                        └─▶ ./migrations/my-vue-app/out/ (migrated project)
                                            + ./migrations/my-vue-app/progress.yaml

---

Configuration File Reference

The migration workflow uses .migrate-config.yaml to track artifact locations across commands.

File Structure

# .migrate-config.yaml (auto-generated by migrate-analyze)
version: "1.0"

projects:
  my-vue-app:
    source_path: ./my-vue-app
    artifacts_dir: ./migrations/my-vue-app
    target_framework: nextjs16
    created_at: "2026-01-20T15:30:00Z"

Path Resolution Logic

All sub-commands (plan, skill, run) automatically resolve artifact paths:

def get_artifacts_dir(project_name):
    """Resolve artifacts directory from config or use default."""
    config_path = ".migrate-config.yaml"

    if exists(config_path):
        config = load_yaml(config_path)
        if project_name in config.get("projects", {}):
            return config["projects"][project_name]["artifacts_dir"]

    # Fallback to default
    return f"./migrations/{project_name}"

Override Behavior

Priority	Source	Example
1 (highest)	--artifacts-output flag	Explicit user override
2	.migrate-config.yaml	Auto-resolved from config
3 (lowest)	Default path	./migrations/{project}/

---

Framework Detection

For detailed detection rules and algorithms, see:

• Framework Detection Algorithm - Detection priority, rules by framework

Quick reference:

Framework	Primary Detection	Key Files
Vue 2/3	vue in package.json	.vue files
React CRA	react-scripts in package.json	src/index.js
Angular	@angular/core in package.json	angular.json
Svelte	svelte in package.json	.svelte files

---

Database Detection

For detailed detection rules and algorithms, see:

• Database Discovery Algorithm - ORM detection, DB type identification, multi-database support

Quick reference:

ORM/Tool	Primary Detection	Key Files
Prisma	prisma, @prisma/client in package.json	prisma/schema.prisma
Drizzle	drizzle-orm, drizzle-kit in package.json	drizzle.config.ts
TypeORM	typeorm in package.json	ormconfig.json, *.entity.ts
Sequelize	sequelize in package.json	.sequelizerc, *.model.js
Mongoose	mongoose in package.json	*.model.js, *.schema.js
Django ORM	django in requirements.txt	models.py, migrations/*.py
SQLAlchemy	sqlalchemy in requirements.txt	alembic.ini, models.py
GORM	gorm.io/gorm in go.mod	*model*.go
Eloquent	laravel/framework in composer.json	app/Models/*.php

Database	Detection Pattern
PostgreSQL	DATABASE_URL=postgres://, pg package
MySQL	DATABASE_URL=mysql://, mysql2 package
SQLite	DATABASE_URL=file:, better-sqlite3 package
MongoDB	MONGODB_URI=, mongoose package
Redis	REDIS_URL=, ioredis / @upstash/redis package

---

Component Mapping

For detailed mapping patterns with code examples, see:

• Component Mapping Strategy - Vue, CRA, Angular, Svelte → Next.js patterns

Quick reference:

Pattern Type	Source → Target
State	ref()/reactive() → useState
Computed	computed() → useMemo
Lifecycle	onMounted() → useEffect(() => {}, [])
Routing	Vue/Angular Router → App Router
Store	Vuex/Pinia/Stores → Zustand

---

State Migration Decision Tree

Is the state...
│
├─ Global (app-wide)?
│   ├─ Complex with actions? → Zustand
│   ├─ Simple shared state? → React Context
│   └─ Server state? → React Query / SWR
│
├─ Component-local?
│   ├─ Primitive value? → useState
│   ├─ Object/Array? → useState with immutable updates
│   └─ Derived value? → useMemo
│
└─ Form state?
    ├─ Simple form? → useState + controlled
    └─ Complex form? → react-hook-form + zod

---

Database Migration Decision Tree

What database type is detected?
│
├─ Relational (PostgreSQL, MySQL, SQLite)?
│   ├─ Current ORM is Prisma? → Keep Prisma (already Next.js compatible)
│   ├─ Current ORM is Drizzle? → Keep Drizzle (already Next.js compatible)
│   ├─ Current ORM is TypeORM/Sequelize? → Migrate to Prisma or Drizzle
│   ├─ Current ORM is Django/SQLAlchemy? → New Prisma or Drizzle schema
│   ├─ Current ORM is GORM? → New Prisma or Drizzle schema
│   ├─ Current ORM is Eloquent? → New Prisma or Drizzle schema
│   └─ No ORM (raw SQL)? → Introduce Prisma or Drizzle
│
├─ NoSQL (MongoDB)?
│   ├─ Current tool is Mongoose? → Prisma (MongoDB) or keep Mongoose
│   └─ No ODM? → Introduce Prisma (MongoDB) or Mongoose
│
├─ Cache/Queue (Redis)?
│   └─ Keep current driver (ioredis / @upstash/redis)
│
└─ No database detected?
    └─ Skip database migration phases (frontend-only project)

---

Architecture Detection

For detailed detection rules and algorithms, see:

• Architecture Detection Algorithm - Source architecture pattern detection, monolith/separated/unknown classification

Quick reference:

Architecture	Detection Pattern
Monolith	Single package.json with frontend+backend deps, fullstack framework (Next.js, Nuxt, Laravel, Django, Rails)
Separated	frontend/+backend/ directories, monorepo config, separate package.json per service
Unknown	No clear indicators, mixed signals → ask user in Phase 2

---

Architecture Pattern Decision Tree

source_architecture?
├─ monolith + component_count < 50 → recommend: fullstack-monolith
├─ monolith + component_count >= 50 → recommend: frontend-backend
├─ separated → recommend: frontend-backend
└─ unknown → ask user

target_architecture?
├─ fullstack-monolith
│   ├─ db_access_from: frontend
│   ├─ Single output directory: {output_dir}/
│   └─ Next.js API Routes + Server Components → DB
│
├─ frontend-backend
│   ├─ db_access_from: backend (default) or both (ask user)
│   ├─ Output: {output_dir}/frontend/ + {output_dir}/backend/
│   ├─ Ask backend framework: fastapi | nestjs | express | go-fiber
│   └─ Sub-Phases: Shared → Backend → Frontend → Integration
│
└─ frontend-only
    ├─ db_access_from: none
    ├─ Single output directory: {output_dir}/
    └─ Frontend only, API client calls existing backend

Config Fields

# Phase 0: Auto-detected
source_architecture: monolith    # monolith | separated | unknown

# Phase 2: User selection
target_architecture: fullstack-monolith  # fullstack-monolith | frontend-backend | frontend-only

# Phase 2: Auto-derived from target_architecture
db_access_from: frontend        # frontend | backend | both | none

# Phase 2: Only for frontend-backend
target_framework_backend: fastapi   # fastapi | nestjs | express | go-fiber

Default (backward compatible): If target_architecture is not set, defaults to fullstack-monolith.

---

Output Structure

All migration artifacts are stored under {artifacts-dir} (default: ./migrations/{project-name}/):

./migrations/{project-name}/        # or custom --artifacts-output path
├── as_is_spec.md           # Phase 1: Current state analysis
├── migration_plan.md       # Phase 2: Migration strategy
├── component_mapping.yaml  # Component mapping table
├── database_mapping.yaml   # Database layer analysis
├── SKILL.md                # Phase 2: Project-specific skill
└── progress.yaml           # Migration progress tracking

Migrated project structure (by target architecture):

fullstack-monolith (default)

{output-dir}/{project-name}/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── api/           # API Routes
│   │   └── {routes}/
│   ├── components/
│   │   ├── ui/           # shadcn components
│   │   └── {migrated}/   # migrated components
│   ├── lib/
│   │   ├── db.ts         # Prisma/Drizzle client
│   │   └── utils.ts
│   └── stores/           # Zustand stores
├── prisma/
│   └── schema.prisma
├── public/
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── next.config.ts

frontend-backend (separated)

{output-dir}/{project-name}/
├── shared/                # Shared types & API contracts
│   ├── types/
│   └── api-contracts/
├── frontend/              # Next.js project
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   ├── lib/
│   │   │   ├── api-client.ts  # Backend API client
│   │   │   └── utils.ts
│   │   └── stores/
│   ├── package.json
│   └── next.config.ts
└── backend/               # Backend project (FastAPI, NestJS, etc.)
    ├── src/
    │   ├── routes/        # API endpoints
    │   ├── services/      # Business logic
    │   ├── models/        # DB models
    │   └── middleware/
    ├── prisma/
    │   └── schema.prisma
    └── package.json       # or requirements.txt, go.mod, etc.

frontend-only

{output-dir}/{project-name}/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── {routes}/
│   ├── components/
│   │   ├── ui/           # shadcn components
│   │   └── {migrated}/   # migrated components
│   ├── lib/
│   │   ├── api-client.ts # Calls existing backend API
│   │   └── utils.ts
│   └── stores/           # Zustand stores
├── public/
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── next.config.ts

---

Agent Delegation Matrix

Phase	Command	Primary Agent	Supporting
0	migrate-analyze	Explore	frontend
1	migrate-2-plan	manager-spec	manager-strategy
2	migrate-2-plan --skill	skill-builder	frontend
3	migrate-3-execute	manager-ddd	frontend, test-guide
Full	friday	manager-migrate-nextjs	All above

---

Quality Gates

Phase 1 (Plan)

• Strategy selected and justified
• Components prioritized
• Risks identified
• migration_plan.md generated (with dynamic initialization section)

migration_plan.md 생성 규칙

Plan 생성 시 .migrate-config.yaml의 target_framework를 확인하여 해당 초기화 절차를 "Project Initialization" 섹션으로 포함합니다.

조건부 섹션 (target_framework 기반):

target_framework	포함할 초기화 가이드	핵심 명령어
nextjs16	@modules/project-initialization.md	create-next-app → shadcn init

migration_plan.md 필수 포함 섹션:

1. Migration Strategy (전략 선택)
2. **Project Initialization** ← target_framework에 따라 동적 포함
   - 프로젝트 생성 명령어
   - UI 라이브러리 초기화
   - 필수 패키지 설치
3. Component Priority (컴포넌트 우선순위)
4. State Migration (상태 관리 전환)
5. Risks & Mitigation (리스크 대응)
6. Timeline (일정)

nextjs16 초기화 요약 (from @modules/project-initialization.md):

# 1. Next.js 프로젝트 생성
npx create-next-app@latest {project-name} \
  --typescript --tailwind --eslint --app --src-dir --turbopack

# 2. 프로젝트 이동 + shadcn/ui 초기화
cd {project-name}
npx shadcn@latest init

# 3. 기본 컴포넌트 + 패키지 설치
npx shadcn@latest add button card input label form dialog toast
npm install zustand react-hook-form @hookform/resolvers zod lucide-react

Phase 2 (Skill)

• Component mappings defined
• Coding conventions established
• Project SKILL.md generated with reference skills
• Template: @templates/project-skill-template.md

Phase 3 (Run)

• Next.js project initialized (per Project Initialization in migration_plan.md)
• shadcn/ui initialized with New York style
• Components migrated
• TypeScript compiles
• Build successful

---

Skill Reference System

migrate-2-plan --skill 명령어 실행 시 생성되는 프로젝트별 SKILL.md는 다음 스킬들을 자동 참조합니다.

Core Reference Skills (Auto-linked)

Skill	Purpose	Auto-Load Condition
jikime-framework-nextjs@16	Next.js 16 App Router 패턴	항상
jikime-framework-nextjs@15	Next.js 15 Breaking Changes	async params 감지 시
jikime-migration-patterns-auth	인증 마이그레이션	인증 코드 감지 시

Conditional Reference Skills

Skill	Trigger Condition
jikime-platform-clerk	Clerk import 감지
jikime-platform-supabase	Supabase import 감지
jikime-library-vercel-ai-sdk	AI SDK import 감지
jikime-library-shadcn	shadcn/ui 사용 시 (기본)

Template Location

templates/project-skill-template.md  ← 프로젝트 SKILL.md 생성 템플릿

How It Works

migrate-2-plan --skill my-app
    │
    ├─▶ 1. as_is_spec.md 분석
    │
    ├─▶ 2. 사용 기술 감지 (Auth, State, Styling)
    │
    ├─▶ 3. 관련 스킬 자동 매핑
    │       - jikime-framework-nextjs@16 (필수)
    │       - jikime-migration-patterns-auth (조건부)
    │       - jikime-platform-* (조건부)
    │
    └─▶ 4. SKILL.md 생성 (Reference Skills 섹션 포함)

---

Progressive Disclosure Modules

For detailed patterns, load on-demand:

Tutorials & Quick Reference

• @modules/project-initialization.md - 프로젝트 초기화 완전 가이드 ⭐⭐ (NEW)
• @modules/migration-flow-tutorial.md - 실제 명령어 사용 흐름 튜토리얼 ⭐
• @modules/cheatsheet.md - 빠른 참조 가이드 ⭐
• @modules/migration-scenario.md - 완전한 마이그레이션 시나리오 (React → Next.js)

Detection & Discovery

• @modules/architecture-detection.md - Architecture Pattern 감지 알고리즘 ⭐ (NEW)
• @modules/database-discovery.md - Database/ORM 감지 알고리즘 ⭐
• @modules/framework-detection.md - Framework 감지 알고리즘

Framework Patterns

• @modules/vue-patterns.md - Vue 2/3 → Next.js conversion rules
• @modules/react-patterns.md - React CRA/Vite → Next.js migration
• @modules/nextjs16-patterns.md - Next.js 16 App Router best practices

Auth Migration

• @jikime-migration-patterns-auth - 인증 마이그레이션 종합 가이드
• @jikime-framework-nextjs@14, @jikime-framework-nextjs@15, @jikime-framework-nextjs@16 - 버전별 업그레이드

---

Git Strategy

branch_prefix: "migrate/"
commit_pattern: "migrate({scope}): {description}"
examples:
  - "migrate(analyze): complete AS_IS analysis for my-vue-app"
  - "migrate(Header): convert Header.vue to Header.tsx"
  - "migrate(routing): implement App Router navigation"
  - "migrate(complete): finish my-vue-app migration"

---

Whitepaper Generation

For detailed whitepaper generation options, structure, and quality checklists, see:

• Whitepaper Generation - Pre-migration and post-migration documentation

Quick Reference

Pre-Migration (--whitepaper):

/jikime:migrate-1-analyze "./my-app" --whitepaper --client "ABC Corp" --lang ko

Generates: 7 documents (cover, executive summary, feasibility, architecture, complexity, roadmap, baseline)

Post-Migration (--whitepaper-report):

/jikime:migrate-3-execute my-app --whitepaper-report --client "ABC Corp"

Generates: 8 documents (cover, summary, performance, security, quality, architecture, ROI, maintenance)

---

Troubleshooting

Skill not triggering

• Try phrases like "migrate Vue to Next.js" or "convert CRA to Next.js"
• Check if .migrate-config.yaml exists for active migration context
• Verify project contains detectable framework patterns (package.json, config files)

Common Migration Issues

Issue	Solution
Module not found	Check import paths - Next.js uses @/ alias for src/
useRouter errors	Use next/navigation for App Router, not next/router
window is not defined	Use dynamic import with ssr: false or useEffect
CSS not applying	Check Tailwind config includes all file paths
API routes 404	Move from pages/api/ to app/api/[route]/route.ts
Hydration mismatch	Ensure server/client render same content initially

Build Errors

• Run npx @next/codemod@latest upgrade for automated fixes
• Check for remaining framework-specific imports: grep -r "from 'vue'" src/
• Verify all components use .tsx extension with proper types

Claude doesn't see skill

• This skill has user-invocable: false - it's auto-loaded by Claude when migration keywords are detected
• Check /context for excluded skills warnings
• Increase SLASH_COMMAND_TOOL_CHAR_BUDGET if many skills excluded

---

Version: 2.3.0 Last Updated: 2026-02-03 Source: Context7 Next.js Documentation + Official Claude Code Skills Specification Standards: Agent Skills (https://agentskills.io) Changelog:

• v2.3.0: Added Architecture Detection section, Architecture Pattern Decision Tree, architecture-specific output structures, architecture-detection.md module reference
• v2.2.0: Added Database Detection section, Database Migration Decision Tree, database-discovery.md module reference, database_mapping.yaml output
• v2.1.0: Applied official Claude Code Skills specification - Added context:fork, agent:Explore, dynamic context injection, troubleshooting section, Agent Skills standard reference
• v2.0.0: Enhanced CRA migration support - Added official @next/codemod, ClientOnly wrapper, incremental migration strategy (Context7 latest)
• v1.8.0: Dynamic Project Initialization in migration_plan.md - target_framework 기반 조건부 초기화 섹션 포함
• v1.7.0: Added project-initialization.md with complete CLI setup guide (create-next-app, shadcn init, packages)
• v1.6.0: Added Skill Reference System - project SKILL.md now auto-references related skills
• v1.5.0: Added migration-flow-tutorial.md, cheatsheet.md with real command examples
• v1.4.0: Added --whitepaper-output and --lang options; Fixed whitepaper output path to project root (./whitepaper/, ./whitepaper-report/)
• v1.3.0: Reorganized templates into pre-migration/ and post-migration/ folders
• v1.2.0: Added Post-Migration Whitepaper with 8 document templates
• v1.1.0: Added Whitepaper Generation feature with 7 document templates