migration-assessment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

分析Next.js Pages Router代码库，以确定迁移复杂度、识别障碍，并给出是否可以进行迁移的建议。

NO MIGRATION WITHOUT ASSESSMENT FIRST

此skill必须在运行

route-conversion

、

component-migration

、

data-layer-migration

或

migration-planning

之前执行。即使用户说“只转换这一个页面”，也要先执行评估。隐藏的障碍（不兼容的依赖项、i18n配置、自定义webpack）可能会在迁移过程中导致失败。

Toolkit Setup

工具包设置

This skill requires the

nextjs-migration-toolkit

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

此skill需要安装

nextjs-migration-toolkit

skill。所有迁移skill都依赖它进行AST分析。

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

0. 确定目标Next.js版本

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

cookies()

headers()

params

, and

searchParams

are sync or async, how fetch caching works, and what package version to install.

在进行任何分析之前，先确定目标版本。检查用户或指令是否已指定版本。如果没有，请询问用户：

Next.js 16（推荐——最新稳定版，完整的异步API，最佳性能）
Next.js 15（异步API，带有临时同步兼容性）
Next.js 14（同步API，最低App Router版本）

将选择保存到

.migration/target-version.txt

（仅保存主版本号，例如

）。

然后读取特定版本的模式文件，了解可用的API：

bash

SKILL_DIR="$(cd "$(dirname "$SKILL_PATH")" && pwd)"
cat "$SKILL_DIR/../version-patterns/nextjs-<version>.md"

这些特定版本的模式将指导所有后续迁移步骤的工作方式——其他所有skill都应参考此文件。这些模式决定了

cookies()

、

headers()

、

params

和

searchParams

是同步还是异步，fetch缓存的工作方式，以及要安装的包版本。

1. Gather Codebase Metrics

1. 收集代码库指标

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>

运行所有分析器以收集数据：

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

2. 分析结果

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

从JSON输出中评估：

路由复杂度：动态路由、兜底路由、API路由和数据获取模式（getStaticProps、getServerSideProps、getStaticPaths）的数量
组件就绪度：服务器兼容组件与仅客户端组件的比例
依赖风险：需要替换的包数量 vs 未知包数量
配置问题：next.config.js分析中的错误与警告数量
死代码：可以先清理的未使用导出的数量

3. Calculate Complexity Score

3. 计算复杂度得分

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

根据以下标准给出1-10分的得分：

路由：每10个路由得1分，如果超过50%使用getServerSideProps则加2分
组件：每20个仅客户端组件得1分
依赖项：每3个需要替换的包得1分，每个无已知替代方案的未知包加2分
配置：如果配置了i18n则加2分，每个webpack自定义配置加1分
规模：1-3 = 简单，4-6 = 中等，7-10 = 复杂

4. Produce Assessment Report

4. 生成评估报告

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

生成结构化报告，包含：

执行摘要：一段关于迁移就绪情况的概述
复杂度得分：带有细分项的数字得分
障碍：迁移前必须解决的关键问题
风险：需要监控的非阻塞性问题
建议：是否可以进行迁移的结论及条件
预估工作量：基于得分的大致T恤尺码估算（S/M/L/XL）

5. Save Assessment

5. 保存评估结果

Write the report to

.migration/assessment.md

in the target project.

将报告写入目标项目的

.migration/assessment.md

文件中。