migrate-to-vinext

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate Next.js to vinext

将Next.js迁移至vinext

vinext reimplements the Next.js API surface on Vite. Existing

app/

pages/

, and

next.config.js

work as-is — migration is a package swap, config generation, and ESM conversion. No changes to application code required.

vinext 在Vite上重新实现了Next.js的API接口。现有的

app/

、

pages/

目录以及

next.config.js

文件可直接使用——迁移仅需替换依赖包、生成配置文件并转换为ESM格式，无需修改应用代码。

FIRST: Verify Next.js Project

第一步：验证Next.js项目

Confirm

next

is in

dependencies

devDependencies

package.json

. If not found, STOP — this skill does not apply.

Detect the package manager from the lockfile:

Lockfile	Manager	Install	Uninstall
`pnpm-lock.yaml`	pnpm	`pnpm add`	`pnpm remove`
`yarn.lock`	yarn	`yarn add`	`yarn remove`
`bun.lockb` / `bun.lock`	bun	`bun add`	`bun remove`
`package-lock.json` or none	npm	`npm install`	`npm uninstall`

Detect the router: if an

app/

directory exists at root or under

src/

, it's App Router. If only

pages/

exists, it's Pages Router. Both can coexist.

确认

package.json

的

dependencies

或

devDependencies

中包含

next

。如果未找到，请停止操作——本技能不适用当前项目。

通过锁文件检测包管理器：

锁文件	管理器	安装命令	卸载命令
`pnpm-lock.yaml`	pnpm	`pnpm add`	`pnpm remove`
`yarn.lock`	yarn	`yarn add`	`yarn remove`
`bun.lockb` / `bun.lock`	bun	`bun add`	`bun remove`
`package-lock.json` 或无锁文件	npm	`npm install`	`npm uninstall`

检测路由类型：如果根目录或

src/

目录下存在

app/

文件夹，则为App Router；如果仅存在

pages/

文件夹，则为Pages Router。两种路由类型可以共存。

Quick Reference

快速参考

Command	Purpose
`vinext check`	Scan project for compatibility issues, produce scored report
`vinext init`	Automated migration — installs deps, generates config, converts to ESM
`vinext dev`	Development server with HMR
`vinext build`	Production build (multi-environment for App Router)
`vinext start`	Local production server
`vinext deploy`	Build and deploy to Cloudflare Workers

命令	用途
`vinext check`	扫描项目兼容性问题，生成评分报告
`vinext init`	自动化迁移——安装依赖、生成配置、转换为ESM格式
`vinext dev`	带有HMR的开发服务器
`vinext build`	生产环境构建（为App Router支持多环境）
`vinext start`	本地生产环境服务器
`vinext deploy`	构建并部署至Cloudflare Workers

Phase 1: Check Compatibility

阶段1：兼容性检查

Run

vinext check

(install vinext first if needed via

npx vinext check

). Review the scored report. If critical incompatibilities exist, inform the user before proceeding.

See references/compatibility.md for supported/unsupported features and ecosystem library status.

运行

vinext check

（如果需要，可先通过

npx vinext check

安装vinext）。查看评分报告。如果存在严重兼容性问题，请在继续操作前告知用户。

查看references/compatibility.md了解支持/不支持的功能以及生态库状态。

Phase 2: Automated Migration (Recommended)

阶段2：自动化迁移（推荐）

Run

vinext init

. This command:

Runs
```
vinext check
```
for a compatibility report
Installs
```
vite
```
as a devDependency (and
```
@vitejs/plugin-rsc
```
for App Router)
Adds
```
"type": "module"
```
to package.json
Renames CJS config files (e.g.,
```
postcss.config.js
```
→
```
.cjs
```
) to avoid ESM conflicts
Adds
```
dev:vinext
```
and
```
build:vinext
```
scripts to package.json
Generates a minimal
```
vite.config.ts
```

This is non-destructive — the existing Next.js setup continues to work alongside vinext. Use the

dev:vinext

script to test before fully switching over.

vinext init

succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3.

运行

vinext init

。该命令会执行以下操作：

运行
```
vinext check
```
生成兼容性报告
安装
```
vite
```
作为开发依赖（如果是App Router，还会安装
```
@vitejs/plugin-rsc
```
）
向
```
package.json
```
中添加
```
"type": "module"
```
重命名CJS配置文件（例如
```
postcss.config.js
```
→
```
.cjs
```
）以避免ESM冲突
向
```
package.json
```
中添加
```
dev:vinext
```
和
```
build:vinext
```
脚本
生成极简版
```
vite.config.ts
```

此操作不会破坏原有配置——现有的Next.js设置可与vinext共存。在完全切换前，可使用

dev:vinext

脚本进行测试。

如果

vinext init

执行成功，可直接跳至阶段4（验证）。如果执行失败或用户希望手动控制，请继续阶段3。

Phase 3: Manual Migration

阶段3：手动迁移

Use this as a fallback when

vinext init

doesn't work or the user wants full control.

当

vinext init

无法工作或用户希望完全掌控迁移过程时，可使用此备选方案。

3a. Replace packages

3a：替换依赖包

bash

undefined

bash

undefined

Example with npm:

npm示例：

npm uninstall next npm install vinext npm install -D vite

App Router only:

仅App Router需要：

npm install -D @vitejs/plugin-rsc

undefined

npm install -D @vitejs/plugin-rsc

undefined

3b. Update scripts

3b：更新脚本

Replace all

next

commands in

package.json

scripts:

Before	After	Notes
`next dev`	`vinext dev`	Dev server with HMR
`next build`	`vinext build`	Production build
`next start`	`vinext start`	Local production server
`next lint`	`vinext lint`	Delegates to eslint/oxlint

Preserve flags:

next dev --port 3001

→

vinext dev --port 3001

替换

package.json

脚本中所有

next

命令：

原命令	新命令	说明
`next dev`	`vinext dev`	带有HMR的开发服务器
`next build`	`vinext build`	生产环境构建
`next start`	`vinext start`	本地生产环境服务器
`next lint`	`vinext lint`	委托给eslint/oxlint执行

保留命令参数：

next dev --port 3001

→

vinext dev --port 3001

。

3c. Convert to ESM

3c：转换为ESM格式

Add

"type": "module"

to package.json. Rename any CJS config files:

```
postcss.config.js
```
→
```
postcss.config.cjs
```
```
tailwind.config.js
```
→
```
tailwind.config.cjs
```
Any other
```
.js
```
config that uses
```
module.exports
```

向

package.json

中添加

"type": "module"

。重命名所有CJS配置文件：

```
postcss.config.js
```
→
```
postcss.config.cjs
```
```
tailwind.config.js
```
→
```
tailwind.config.cjs
```
其他使用
```
module.exports
```
的
```
.js
```
配置文件

3d. Generate vite.config.ts

3d：生成vite.config.ts

See references/config-examples.md for config variants per router and deployment target.

Pages Router (minimal):

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

App Router (minimal):

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

vinext auto-registers

@vitejs/plugin-rsc

for App Router when the

rsc

option is not explicitly

false

. No manual RSC plugin config needed for local development.

查看references/config-examples.md获取不同路由类型和部署目标的配置示例。

Pages Router（极简版）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

App Router（极简版）：

import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });

当

rsc

选项未显式设置为

false

时，vinext会自动为App Router注册

@vitejs/plugin-rsc

。本地开发无需手动配置RSC插件。

Phase 4: Cloudflare Deployment (Optional)

阶段4：Cloudflare部署（可选）

If the user wants to deploy to Cloudflare Workers, the simplest path is

vinext deploy

— it auto-generates

wrangler.jsonc

, worker entry, and Vite config if missing, installs

@cloudflare/vite-plugin

and

wrangler

, then builds and deploys.

For manual setup or custom worker entries, see references/config-examples.md.

如果用户希望部署至Cloudflare Workers，最简单的方式是运行

vinext deploy

——该命令会自动生成

wrangler.jsonc

、Worker入口文件和缺失的Vite配置，安装

@cloudflare/vite-plugin

和

wrangler

，然后执行构建和部署。

如需手动设置或自定义Worker入口，请查看references/config-examples.md。

Phase 5: Verify

阶段5：验证

Run
```
vinext dev
```
to start the development server
Confirm the server starts without errors
Navigate key routes and check functionality
Report the result to the user — if errors occur, share full output

See references/troubleshooting.md for common migration errors.

运行
```
vinext dev
```
启动开发服务器
确认服务器无错误启动
访问关键路由并检查功能是否正常
向用户反馈结果——如果出现错误，分享完整输出信息

查看references/troubleshooting.md了解常见迁移错误。

Known Limitations

已知限制

Feature	Status
`next/image` optimization	Remote images via @unpic; no build-time optimization
`next/font/google`	CDN-loaded, not self-hosted
Domain-based i18n	Not supported; path-prefix i18n works
`next/jest`	Not supported; use Vitest
Turbopack/webpack config	Ignored; use Vite plugins instead
`runtime` / `preferredRegion`	Route segment configs ignored
PPR (Partial Prerendering)	Use `"use cache"` directive instead (Next.js 16 approach)

功能	状态
`next/image` 优化	支持通过@unpic处理远程图片；不支持构建时优化
`next/font/google`	支持CDN加载，不支持自托管
基于域名的国际化	不支持；路径前缀式国际化可用
`next/jest`	不支持；使用Vitest替代
Turbopack/webpack配置	会被忽略；请使用Vite原生插件替代
`runtime` / `preferredRegion`	路由段配置会被忽略
PPR（部分预渲染）	使用 `"use cache"` 指令替代（Next.js 16的实现方式）

Anti-patterns

反模式

Do not modify
app/
,
pages/
, or application code. vinext shims all
```
next/*
```
imports — no import rewrites needed.
Do not rewrite
next/*
imports to
```
vinext/*
```
in application code. Imports like
```
next/image
```
,
```
next/link
```
,
```
next/server
```
resolve automatically.
Do not copy webpack/Turbopack config into Vite config. Use Vite-native plugins instead.
Do not skip the compatibility check. Run
```
vinext check
```
before migration to surface issues early.
Do not remove
next.config.js
unless replacing it with
```
next.config.ts
```
or
```
.mjs
```
. vinext reads it for redirects, rewrites, headers, basePath, i18n, images, and env config.

请勿修改
app/
、
pages/
目录或应用代码。vinext会自动适配所有
```
next/*
```
导入——无需重写导入语句。
请勿将
next/*
导入重写为
vinext/*
。
```
next/image
```
、
```
next/link
```
、
```
next/server
```
等导入会自动解析。
请勿将webpack/Turbopack配置复制到Vite配置中。请使用Vite原生插件替代。
请勿跳过兼容性检查。迁移前运行
```
vinext check
```
可提前发现问题。
请勿删除
next.config.js
，除非用
```
next.config.ts
```
或
```
.mjs
```
替代。vinext会读取该文件中的重定向、重写、请求头、basePath、国际化、图片和环境变量配置。