Back to Details

nextjs-migration-toolkit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Next.js Migration Toolkit

Next.js 迁移工具包

AST-powered analysis and transform tools for Next.js Pages Router to App Router migration. This skill is a dependency for all other migration skills — install it alongside them.
基于AST的分析与转换工具，用于将Next.js Pages Router迁移至App Router。本skill是所有其他迁移skill的依赖项，请与它们一同安装。

Setup

安装设置

Before using any migration skill, run the setup script to install toolkit dependencies:
bash
TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")" && pwd)"
if [ ! -d "$TOOLKIT_DIR/node_modules" ]; then
  cd "$TOOLKIT_DIR" && npm install --silent 2>/dev/null
fi
在使用任何迁移skill之前，请运行设置脚本以安装工具包依赖：
bash
TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")" && pwd)"
if [ ! -d "$TOOLKIT_DIR/node_modules" ]; then
  cd "$TOOLKIT_DIR" && npm install --silent 2>/dev/null
fi

Available Commands

可用命令

All commands output structured JSON to stdout.
所有命令均向标准输出（stdout）返回结构化JSON。

Analyzers

分析工具

bash
undefined
bash
undefined

Extract all routes from pages/ directory

从pages/目录提取所有路由

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze routes <pagesDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze routes <pagesDir>

Inventory components and classify as server/client

盘点组件并分类为服务端/客户端组件

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze components <srcDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze components <srcDir>

Map dependencies to App Router equivalents

将依赖项映射为App Router等效项

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dependencies <packageJsonPath>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dependencies <packageJsonPath>

Find unused exports

查找未使用的导出

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dead-code <srcDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dead-code <srcDir>

Audit next.config.js for migration issues

检查next.config.js是否存在迁移问题

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze config <nextConfigPath>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze config <nextConfigPath>

Extract props from a component

从组件提取属性

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze props <componentFile>
undefined
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze props <componentFile>
undefined

Transforms (dry-run by default)

转换工具（默认启用空运行）

bash
undefined
bash
undefined

Rewrite imports (next/router → next/navigation, etc.)

重写导入语句（如next/router → next/navigation等）

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform imports <file> --dry-run
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform imports <file> --dry-run

Migrate data fetching patterns

迁移数据获取模式

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform data-fetching <file>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform data-fetching <file>

Update router usage patterns

更新路由使用模式

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform router <file>
undefined
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform router <file>
undefined

Validation

验证工具

bash
undefined
bash
undefined

Validate migrated app/ directory for common issues

验证已迁移的app/目录是否存在常见问题

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" validate <appDir>
undefined
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" validate <appDir>
undefined

Output Format

输出格式

All commands return JSON. Example route analysis output:
json
{
  "routes": [
    {
      "file": "pages/blog/[slug].tsx",
      "route": "/blog/:slug",
      "type": "dynamic",
      "dataFetching": ["getStaticProps", "getStaticPaths"]
    }
  ],
  "summary": { "total": 1, "static": 0, "dynamic": 1, "api": 0 }
}
所有命令均返回JSON。路由分析输出示例：
json
{
  "routes": [
    {
      "file": "pages/blog/[slug].tsx",
      "route": "/blog/:slug",
      "type": "dynamic",
      "dataFetching": ["getStaticProps", "getStaticPaths"]
    }
  ],
  "summary": { "total": 1, "static": 0, "dynamic": 1, "api": 0 }
}