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
,
,
, or
. 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
skill to be installed. All migration skills depend on it for AST analysis.
bash
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.,
).
Then read the version-specific patterns file to understand what APIs are available:
bash
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
,
,
, and
are sync or async, how fetch caching works, and what package version to install.
1. Gather Codebase Metrics
Run all analyzers to collect data:
bash
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
in the target project.