migration-assessment

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.