jikime-migration-to-nextjs

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](modules/framework-detection.md) - 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](modules/database-discovery.md) - 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](modules/component-mapping.md) - 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](modules/architecture-detection.md) - 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](modules/whitepaper.md) - 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 SLASHCOMMANDTOOLCHARBUDGET 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 migrationplan.md - targetframework 기반 조건부 초기화 섹션 포함
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

Installation

Similar popular skills

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md

Dynamic Context (auto-loaded)

Current Dependencies

Framework Detection

Migration Config

Overview

Target Stack

Supported Source Frameworks

Migration Workflow

Configuration File Reference

File Structure

Path Resolution Logic

Override Behavior

Framework Detection

Database Detection

Component Mapping

State Migration Decision Tree

Database Migration Decision Tree

Architecture Detection

Architecture Pattern Decision Tree

Config Fields

Output Structure

fullstack-monolith (default)

frontend-backend (separated)

frontend-only

Agent Delegation Matrix

Quality Gates

Phase 1 (Plan)

migration_plan.md 생성 규칙

Phase 2 (Skill)

Phase 3 (Run)

Skill Reference System

Core Reference Skills (Auto-linked)

Conditional Reference Skills

Template Location

How It Works

Progressive Disclosure Modules

Tutorials & Quick Reference

Detection & Discovery

Framework Patterns

Auth Migration

Git Strategy

Whitepaper Generation

Quick Reference

Troubleshooting

Skill not triggering

Common Migration Issues

Build Errors

Claude doesn't see skill