| name | migration-assessment |
| description | Use when starting a Next.js Pages Router to App Router migration, evaluating migration feasibility, or auditing codebase readiness. Run this BEFORE any other migration skill.
|
Migration Assessment
Analyze a Next.js Pages Router codebase to determine migration complexity, identify blockers, and produce a go/no-go recommendation.
NO MIGRATION WITHOUT ASSESSMENT FIRST
This skill MUST run before route-conversion, component-migration, data-layer-migration, or migration-planning. Even if the user says "just convert this one page" — run assessment first. Hidden blockers (incompatible dependencies, i18n config, custom webpack) can derail a migration mid-flight.
Toolkit Setup
This skill requires the nextjs-migration-toolkit skill to be installed. All migration skills depend on it for AST analysis.
TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")/../nextjs-migration-toolkit" && pwd)"
if [ ! -f "$TOOLKIT_DIR/package.json" ]; then
echo "ERROR: nextjs-migration-toolkit is not installed." >&2
echo "Run: npx skills add blazity/next-migration-skills -s nextjs-migration-toolkit" >&2
echo "Then retry this skill." >&2
exit 1
fi
bash "$TOOLKIT_DIR/scripts/setup.sh" >/dev/null
Steps
0. Determine Target Next.js Version
Before any analysis, establish the target version. Check if the user or instruction already specified one. If not, ask the user:
- Next.js 16 (recommended — latest stable, full async APIs, best performance)
- Next.js 15 (async APIs with temporary sync compatibility)
- Next.js 14 (synchronous APIs, minimum App Router version)
Save the choice to .migration/target-version.txt (just the major version number, e.g., 16).
Then read the version-specific patterns file to understand what APIs are available:
SKILL_DIR="$(cd "$(dirname "$SKILL_PATH")" && pwd)"
cat "$SKILL_DIR/../version-patterns/nextjs-<version>.md"
These version-specific patterns govern how ALL subsequent migration steps work — every other skill should reference this file. The patterns determine whether cookies(), headers(), params, and searchParams are sync or async, how fetch caching works, and what package version to install.
1. Gather Codebase Metrics
Run all analyzers to collect data:
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze routes <pagesDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze components <srcDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dependencies <packageJsonPath>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dead-code <srcDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze config <nextConfigPath>
2. Analyze Results
From the JSON output, assess:
- Route complexity: Count of dynamic routes, catch-all routes, API routes, and data-fetching patterns (getStaticProps, getServerSideProps, getStaticPaths)
- Component readiness: Ratio of server-compatible vs client-only components
- Dependency risk: Number of packages needing replacement vs unknown packages
- Config issues: Count of errors vs warnings in next.config.js analysis
- Dead code: Amount of unused exports that can be cleaned up first
3. Calculate Complexity Score
Score from 1-10 based on:
- Routes: 1 point per 10 routes, +2 if >50% use getServerSideProps
- Components: 1 point per 20 client-only components
- Dependencies: 1 point per 3 replaceable packages, +2 per unknown package with no known replacement
- Config: +2 if i18n is configured, +1 per webpack customization
- Scale: 1-3 = Simple, 4-6 = Moderate, 7-10 = Complex
4. Produce Assessment Report
Generate a structured report with:
- Executive summary: One-paragraph migration readiness overview
- Complexity score: Numeric score with breakdown
- Blockers: Critical issues that must be resolved before migration
- Risks: Non-blocking concerns to monitor
- Recommendations: Go/No-go with conditions
- Estimated effort: Rough t-shirt sizing (S/M/L/XL) based on score
5. Save Assessment
Write the report to .migration/assessment.md in the target project.
