nextjs-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Validator

Validates Next.js 16 configuration and prevents deprecated patterns. AI assistants often generate Next.js 14/15 patterns - this skill enforces Next.js 16.

验证Next.js 16配置并防止已弃用的模式。AI助手通常会生成Next.js 14/15的模式——本工具强制遵循Next.js 16规范。

When This Activates

触发场景

Setting up a new Next.js project
Before any Next.js development work
Auditing existing Next.js projects
After AI generates Next.js code
CI/CD pipeline validation

搭建新的Next.js项目时
开展任何Next.js开发工作前
审计现有Next.js项目时
AI生成Next.js代码后
CI/CD流水线验证环节

Quick Start

快速开始

bash

python3 ~/.claude/skills/nextjs-validator/scripts/validate.py --root .
python3 ~/.claude/skills/nextjs-validator/scripts/validate.py --root . --strict

bash

python3 ~/.claude/skills/nextjs-validator/scripts/validate.py --root .
python3 ~/.claude/skills/nextjs-validator/scripts/validate.py --root . --strict

What Gets Checked

检查内容

1. Package Version

1. 包版本

json

// GOOD: v16+
"next": "^16.0.0"

// BAD: v15 or earlier
"next": "^15.0.0"

json

// GOOD: v16+
"next": "^16.0.0"

// BAD: v15或更早版本
"next": "^15.0.0"

2. Proxy vs Middleware

2. Proxy与Middleware

GOOD - Next.js 16:

typescript

// proxy.ts (Node.js runtime - REQUIRED)
import { createProxy } from 'next/proxy';
export const proxy = createProxy();

BAD - Deprecated:

typescript

// middleware.ts (Edge runtime - DEPRECATED)
export function middleware() { }

推荐 - Next.js 16：

typescript

// proxy.ts (Node.js 运行时 - 必需)
import { createProxy } from 'next/proxy';
export const proxy = createProxy();

已弃用：

typescript

// middleware.ts (Edge 运行时 - 已弃用)
export function middleware() { }

3. App Router Structure

3. App Router 结构

GOOD:

app/
├── layout.tsx          # Root layout
├── page.tsx            # Home page
├── (routes)/           # Route groups
│   ├── dashboard/
│   │   └── page.tsx
│   └── settings/
│       └── page.tsx
└── api/                # API routes (optional)

BAD - Pages Router (deprecated):

pages/
├── _app.tsx
├── index.tsx
└── api/

推荐：

app/
├── layout.tsx          # 根布局
├── page.tsx            # 首页
├── (routes)/           # 路由组
│   ├── dashboard/
│   │   └── page.tsx
│   └── settings/
│       └── page.tsx
└── api/                # API 路由（可选）

不推荐 - Pages Router（已弃用）：

pages/
├── _app.tsx
├── index.tsx
└── api/

4. Cache Components &

use cache

4. 缓存组件与

use cache

GOOD - Next.js 16:

typescript

// app/dashboard/page.tsx
'use cache';

export default async function Dashboard() {
  const data = await fetch('/api/data');
  return <DashboardView data={data} />;
}

推荐 - Next.js 16：

typescript

// app/dashboard/page.tsx
'use cache';

export default async function Dashboard() {
  const data = await fetch('/api/data');
  return <DashboardView data={data} />;
}

5. Server Actions

GOOD:

typescript

// app/actions.ts
'use server';

export async function createItem(formData: FormData) {
  // Server-side logic
}

推荐：

typescript

// app/actions.ts
'use server';

export async function createItem(formData: FormData) {
  // 服务端逻辑
}

6. Turbopack Configuration

6. Turbopack 配置

GOOD - Default in Next.js 16:

json

// next.config.ts (Turbopack is default, no config needed)

BAD - Disabling Turbopack:

json

// Don't disable unless absolutely necessary
experimental: {
  turbo: false  // BAD
}

推荐 - Next.js 16 默认配置：

json

// next.config.ts (Turbopack 是默认配置，无需额外设置)

不推荐 - 禁用 Turbopack：

json

// 除非绝对必要，否则不要禁用
experimental: {
  turbo: false  // 不推荐
}

7. Config File Format

7. 配置文件格式

GOOD - TypeScript config:

typescript

// next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  // ...
};

export default config;

BAD - JavaScript config:

javascript

// next.config.js - Prefer .ts
module.exports = { }

推荐 - TypeScript 配置：

typescript

// next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  // ...
};

export default config;

不推荐 - JavaScript 配置：

javascript

// next.config.js - 优先使用.ts格式
module.exports = { }

Deprecated Patterns to Avoid

需要避免的已弃用模式

Deprecated (v15-)	Replacement (v16+)
`middleware.ts`	`proxy.ts`
`getServerSideProps`	Server Components + `use cache`
`getStaticProps`	Server Components + `use cache`
`getStaticPaths`	`generateStaticParams`
`_app.tsx`	`app/layout.tsx`
`_document.tsx`	`app/layout.tsx`
`pages/` directory	`app/` directory
`next/router`	`next/navigation`
`useRouter()` (pages)	`useRouter()` from `next/navigation`

已弃用（v15及更早版本）	替代方案（v16+）
`middleware.ts`	`proxy.ts`
`getServerSideProps`	服务端组件 + `use cache`
`getStaticProps`	服务端组件 + `use cache`
`getStaticPaths`	`generateStaticParams`
`_app.tsx`	`app/layout.tsx`
`_document.tsx`	`app/layout.tsx`
`pages/` 目录	`app/` 目录
`next/router`	`next/navigation`
`useRouter()` (pages)	来自 `next/navigation` 的 `useRouter()`

Next.js 16 Features to Use

Next.js 16 推荐使用的功能

Cache Components

缓存组件

typescript

'use cache';

// Entire component cached
export default async function CachedPage() {
  const data = await fetchData();
  return <View data={data} />;
}

typescript

'use cache';

// 整个组件将被缓存
export default async function CachedPage() {
  const data = await fetchData();
  return <View data={data} />;
}

Partial Pre-Rendering (PPR)

部分预渲染（PPR）

typescript

// next.config.ts
const config: NextConfig = {
  experimental: {
    ppr: true,
  },
};

typescript

// next.config.ts
const config: NextConfig = {
  experimental: {
    ppr: true,
  },
};

Next.js DevTools MCP

AI-assisted debugging with contextual insight:

typescript

// Enable in development
// Works with Claude Code and other MCP-compatible tools

具备上下文洞察的AI辅助调试：

typescript

// 在开发环境中启用
// 兼容Claude Code及其他MCP兼容工具

Parallel Routes

并行路由

app/
├── @modal/
│   └── login/
│       └── page.tsx
├── @sidebar/
│   └── default.tsx
└── layout.tsx

app/
├── @modal/
│   └── login/
│       └── page.tsx
├── @sidebar/
│   └── default.tsx
└── layout.tsx

Intercepting Routes

拦截路由

app/
├── feed/
│   └── page.tsx
├── photo/
│   └── [id]/
│       └── page.tsx
└── @modal/
    └── (.)photo/
        └── [id]/
            └── page.tsx

app/
├── feed/
│   └── page.tsx
├── photo/
│   └── [id]/
│       └── page.tsx
└── @modal/
    └── (.)photo/
        └── [id]/
            └── page.tsx

Validation Output

验证输出示例

=== Next.js 16 Validation Report ===

Package Version: next@16.1.0 ✓

File Structure:
  ✓ Using app/ directory (App Router)
  ✗ Found pages/ directory - migrate to App Router
  ✓ Found proxy.ts
  ✗ Found middleware.ts - migrate to proxy.ts

Patterns:
  ✓ Using Server Components
  ✗ Found getServerSideProps in 2 files
  ✓ Using next/navigation

Config:
  ✓ next.config.ts (TypeScript)
  ✓ Turbopack enabled (default)

Summary: 2 issues found
  - Migrate pages/ to app/ directory
  - Replace middleware.ts with proxy.ts

=== Next.js 16 验证报告 ===

包版本: next@16.1.0 ✓

文件结构:
  ✓ 使用app/目录（App Router）
  ✗ 检测到pages/目录 - 请迁移至App Router
  ✓ 检测到proxy.ts
  ✗ 检测到middleware.ts - 请迁移至proxy.ts

模式检查:
  ✓ 使用服务端组件
  ✗ 在2个文件中检测到getServerSideProps
  ✓ 使用next/navigation

配置检查:
  ✓ next.config.ts（TypeScript格式）
  ✓ Turbopack已启用（默认配置）

总结: 发现2个问题
  - 将pages/目录迁移至app/目录
  - 将middleware.ts替换为proxy.ts

Migration Guide

迁移指南

From middleware.ts to proxy.ts

从middleware.ts迁移至proxy.ts

Before (v15):

typescript

// middleware.ts
import { NextResponse } from 'next/server';

export function middleware(request) {
  // Edge runtime
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*'],
};

After (v16):

typescript

// proxy.ts
import { createProxy } from 'next/proxy';

export const proxy = createProxy({
  // Node.js runtime
  async handle(request) {
    // Full Node.js APIs available
    return request;
  },
  matcher: ['/dashboard/:path*'],
});

迁移前（v15）：

typescript

// middleware.ts
import { NextResponse } from 'next/server';

export function middleware(request) {
  // Edge 运行时
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*'],
};

迁移后（v16）：

typescript

// proxy.ts
import { createProxy } from 'next/proxy';

export const proxy = createProxy({
  // Node.js 运行时
  async handle(request) {
    // 可使用完整的Node.js API
    return request;
  },
  matcher: ['/dashboard/:path*'],
});

From getServerSideProps to Server Components

从getServerSideProps迁移至服务端组件

Before:

typescript

// pages/dashboard.tsx
export async function getServerSideProps() {
  const data = await fetchData();
  return { props: { data } };
}

export default function Dashboard({ data }) {
  return <View data={data} />;
}

After:

typescript

// app/dashboard/page.tsx
export default async function Dashboard() {
  const data = await fetchData();
  return <View data={data} />;
}

迁移前：

typescript

// pages/dashboard.tsx
export async function getServerSideProps() {
  const data = await fetchData();
  return { props: { data } };
}

export default function Dashboard({ data }) {
  return <View data={data} />;
}

迁移后：

typescript

// app/dashboard/page.tsx
export default async function Dashboard() {
  const data = await fetchData();
  return <View data={data} />;
}

CI/CD Integration

CI/CD 集成

yaml

undefined

yaml

undefined

.github/workflows/validate.yml

name: Validate Next.js 16 run: | python3 ~/.claude/skills/nextjs-validator/scripts/validate.py
--root .
--strict
--ci

undefined

name: Validate Next.js 16 run: | python3 ~/.claude/skills/nextjs-validator/scripts/validate.py
--root .
--strict
--ci

undefined

Integration

集成工具

```
tailwind-validator
```
- Validate Tailwind v4 config
```
biome-validator
```
- Validate Biome 2.3+ config
```
clerk-validator
```
- Validate Clerk auth setup

```
tailwind-validator
```
- 验证Tailwind v4配置
```
biome-validator
```
- 验证Biome 2.3+配置
```
clerk-validator
```
- 验证Clerk认证设置

nextjs-validator

Original

Translation

Next.js Validator

Next.js Validator

When This Activates

触发场景

Quick Start

快速开始

What Gets Checked

检查内容

1. Package Version

1. 包版本

2. Proxy vs Middleware

2. Proxy与Middleware

3. App Router Structure

3. App Router 结构

4. Cache Components & use cache

4. 缓存组件与use cache

5. Server Actions

5. Server Actions

6. Turbopack Configuration

6. Turbopack 配置

7. Config File Format

7. 配置文件格式

Deprecated Patterns to Avoid

需要避免的已弃用模式

Next.js 16 Features to Use

Next.js 16 推荐使用的功能

Cache Components

缓存组件

Partial Pre-Rendering (PPR)

部分预渲染（PPR）

Next.js DevTools MCP

Next.js DevTools MCP

Parallel Routes

并行路由

Intercepting Routes

拦截路由

Validation Output

验证输出示例

Migration Guide

迁移指南

From middleware.ts to proxy.ts

从middleware.ts迁移至proxy.ts

From getServerSideProps to Server Components

从getServerSideProps迁移至服务端组件

CI/CD Integration

CI/CD 集成

.github/workflows/validate.yml

.github/workflows/validate.yml

Integration

集成工具

4. Cache Components &
`use cache`

4. 缓存组件与
`use cache`