migrate-to-vinext by cloudflare/vinext
npx skills add https://github.com/cloudflare/vinext --skill migrate-to-vinextvinext 在 Vite 上重新实现了 Next.js 的 API 接口。现有的 app/、pages/ 和 next.config.js 可以直接工作——迁移只需更换包、生成配置和转换为 ESM。无需更改应用程序代码。
确认 package.json 的 dependencies 或 devDependencies 中包含 next。如果未找到,请停止——此技能不适用。
根据锁文件检测包管理器:
| 锁文件 | 管理器 | 安装 |
|---|
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 卸载 |
|---|
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。两者可以共存。
| 命令 | 用途 |
|---|---|
vinext check | 扫描项目以查找兼容性问题,生成评分报告 |
vinext init | 自动迁移——安装依赖、生成配置、转换为 ESM |
vinext dev | 带 HMR 的开发服务器 |
vinext build | 生产构建(App Router 支持多环境) |
vinext start | 本地生产服务器 |
vinext deploy | 构建并部署到 Cloudflare Workers |
运行 vinext check(如果需要,可通过 npx vinext check 先安装 vinext)。查看评分报告。如果存在严重的不兼容问题,请在继续之前告知用户。
有关支持/不支持的功能和生态系统库状态,请参阅 references/compatibility.md。
运行 vinext init。此命令:
vinext check 生成兼容性报告vite 安装为 devDependency(App Router 还需安装 @vitejs/plugin-rsc)"type": "module"postcss.config.js → .cjs)以避免 ESM 冲突dev:vinext 和 build:vinext 脚本vite.config.ts这是非破坏性的——现有的 Next.js 设置可以继续与 vinext 一起工作。在完全切换之前,使用 dev:vinext 脚本进行测试。
如果 vinext init 成功,请跳转到阶段 4(验证)。如果失败或用户希望手动控制,请继续阶段 3。
当 vinext init 不工作或用户希望完全控制时,使用此方法作为备用方案。
# 使用 npm 的示例:
npm uninstall next
npm install vinext
npm install -D vite
# 仅限 App Router:
npm install -D @vitejs/plugin-rsc
替换 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。
向 package.json 添加 "type": "module"。重命名任何 CJS 配置文件:
postcss.config.js → postcss.config.cjstailwind.config.js → tailwind.config.cjsmodule.exports 的 .js 配置文件有关每种路由和部署目标的配置变体,请参阅 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 插件。
如果用户希望部署到 Cloudflare Workers,请使用 vinext deploy。如果缺少,它会自动生成 wrangler.jsonc、worker 入口和 Vite 配置,安装 @cloudflare/vite-plugin 和 wrangler,然后构建并部署。
有关手动设置或自定义 worker 入口,请参阅 references/config-examples.md。
要访问 Cloudflare 绑定(D1、R2、KV、AI、Queues、Durable Objects 等),请在任意服务器组件、路由处理器或服务器操作中使用 import { env } from "cloudflare:workers":
import { env } from "cloudflare:workers";
export default async function Page() {
const result = await env.DB.prepare("SELECT * FROM posts").all();
return <div>{JSON.stringify(result)}</div>;
}
之所以可行,是因为 @cloudflare/vite-plugin 在 workerd 中运行服务器环境,而 cloudflare:workers 是其中的原生模块。无需自定义 worker 入口,无需 getPlatformProxy(),无需特殊配置。只需导入并使用即可。
绑定必须在 wrangler.jsonc 中定义。对于 TypeScript 类型,请运行 wrangler types。
重要提示: 不要使用 getPlatformProxy()、getRequestContext() 或带有 fetch(request, env) 的自定义 worker 入口来访问绑定。这些是旧模式。cloudflare:workers 是推荐的方法,并且开箱即用与 vinext 配合。
要部署到 Vercel、Netlify、AWS、Deno Deploy 或任何其他 Nitro 支持的平台,请添加 Nitro Vite 插件:
npm install nitro
// vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";
export default defineConfig({
plugins: [vinext(), nitro()],
});
构建和部署:
NITRO_PRESET=vercel npx vite build # Vercel
NITRO_PRESET=netlify npx vite build # Netlify
NITRO_PRESET=deno_deploy npx vite build # Deno Deploy
NITRO_PRESET=node npx vite build # Node.js 服务器
在大多数 CI/CD 环境中,Nitro 会自动检测平台,因此通常不需要预设。
注意: 对于 Cloudflare Workers,Nitro 可以工作,但推荐使用原生集成(vinext deploy / @cloudflare/vite-plugin),以获得与 cloudflare:workers 绑定、KV 缓存和单命令部署的最佳开发者体验。
vinext dev 启动开发服务器有关常见的迁移错误,请参阅 references/troubleshooting.md。
| 功能 | 状态 |
|---|---|
next/image 优化 | 通过 @unpic 支持远程图片;不支持构建时优化 |
next/font/google | CDN 加载,非自托管 |
| 基于域名的国际化 | 不支持;基于路径前缀的国际化有效 |
next/jest | 不支持;使用 Vitest |
| Turbopack/webpack 配置 | 忽略;改用 Vite 插件 |
runtime / preferredRegion | 路由段配置被忽略 |
| PPR(部分预渲染) | 改用 "use cache" 指令(Next.js 16 方法) |
app/、pages/ 或应用程序代码。 vinext 垫片了所有 next/* 导入——无需重写导入。next/* 导入重写为 vinext/*。 像 next/image、next/link、next/server 这样的导入会自动解析。vinext check 以尽早发现问题。next.config.js,除非用 next.config.ts 或 .mjs 替换它。vinext 会读取它以获取重定向、重写、标头、basePath、i18n、图片和环境配置。getPlatformProxy() 或自定义 worker 入口来访问绑定。 改用 import { env } from "cloudflare:workers"。这是现代模式,开箱即用与 vinext 和 @cloudflare/vite-plugin 配合。vinext deploy / @cloudflare/vite-plugin 提供了与 cloudflare:workers 绑定、KV 缓存和图片优化的最佳体验。Nitro 适用于 Cloudflare,但推荐原生设置。每周安装量
1.6K
仓库
GitHub 星标
6.4K
首次出现
2026年2月24日
安全审计
安装于
codex1.6K
opencode1.6K
github-copilot1.6K
cursor1.6K
gemini-cli1.6K
kimi-cli1.6K
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.
Confirm next is in dependencies or devDependencies in 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 |
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.
| 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 |
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.
Run vinext init. This command:
vinext check for a compatibility reportvite as a devDependency (and @vitejs/plugin-rsc for App Router)"type": "module" to package.jsonpostcss.config.js → .cjs) to avoid ESM conflictsdev:vinext and build:vinext scripts to package.jsonvite.config.tsThis is non-destructive — the existing Next.js setup continues to work alongside vinext. Use the dev:vinext script to test before fully switching over.
If vinext init succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3.
Use this as a fallback when vinext init doesn't work or the user wants full control.
# Example with npm:
npm uninstall next
npm install vinext
npm install -D vite
# App Router only:
npm install -D @vitejs/plugin-rsc
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 |
Preserve flags: next dev --port 3001 → vinext dev --port 3001.
Add "type": "module" to package.json. Rename any CJS config files:
postcss.config.js → postcss.config.cjstailwind.config.js → tailwind.config.cjs.js config that uses module.exportsSee 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.
If the user wants to deploy to Cloudflare Workers, use 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.
To access Cloudflare bindings (D1, R2, KV, AI, Queues, Durable Objects, etc.), use import { env } from "cloudflare:workers" in any server component, route handler, or server action:
import { env } from "cloudflare:workers";
export default async function Page() {
const result = await env.DB.prepare("SELECT * FROM posts").all();
return <div>{JSON.stringify(result)}</div>;
}
This works because @cloudflare/vite-plugin runs server environments in workerd, where cloudflare:workers is a native module. No custom worker entry, no getPlatformProxy(), no special configuration needed. Just import and use.
Bindings must be defined in wrangler.jsonc. For TypeScript types, run wrangler types.
IMPORTANT: Do not use getPlatformProxy(), getRequestContext(), or custom worker entries with fetch(request, env) to access bindings. These are older patterns. cloudflare:workers is the recommended approach and works out of the box with vinext.
For deploying to Vercel, Netlify, AWS, Deno Deploy, or any other Nitro-supported platform, add the Nitro Vite plugin:
npm install nitro
// vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";
export default defineConfig({
plugins: [vinext(), nitro()],
});
Build and deploy:
NITRO_PRESET=vercel npx vite build # Vercel
NITRO_PRESET=netlify npx vite build # Netlify
NITRO_PRESET=deno_deploy npx vite build # Deno Deploy
NITRO_PRESET=node npx vite build # Node.js server
Nitro auto-detects the platform in most CI/CD environments, so the preset is often unnecessary.
Note: For Cloudflare Workers, Nitro works but the native integration (vinext deploy / @cloudflare/vite-plugin) is recommended for the best developer experience with cloudflare:workers bindings, KV caching, and one-command deploys.
vinext dev to start the development serverSee references/troubleshooting.md for common migration errors.
| 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) |
app/, pages/, or application code. vinext shims all next/* imports — no import rewrites needed.next/* imports to vinext/* in application code. Imports like next/image, next/link, next/server resolve automatically.vinext check before migration to surface issues early.Weekly Installs
1.6K
Repository
GitHub Stars
6.4K
First Seen
Feb 24, 2026
Security Audits
Gen Agent Trust HubPassSocketFailSnykPass
Installed on
codex1.6K
opencode1.6K
github-copilot1.6K
cursor1.6K
gemini-cli1.6K
kimi-cli1.6K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
AI智能体长期记忆系统 - 精英级架构,融合6种方法,永不丢失上下文
1,200 周安装
AI新闻播客制作技能:实时新闻转对话式播客脚本与音频生成
1,200 周安装
Word文档处理器:DOCX创建、编辑、分析与修订痕迹处理全指南 | 自动化办公解决方案
1,200 周安装
React Router 框架模式指南:全栈开发、文件路由、数据加载与渲染策略
1,200 周安装
Nano Banana AI 图像生成工具:使用 Gemini 3 Pro 生成与编辑高分辨率图像
1,200 周安装
SVG Logo Designer - AI 驱动的专业矢量标识设计工具,生成可缩放品牌标识
1,200 周安装
bun remove |
package-lock.json or none | npm | npm install | npm uninstall |
| Build and deploy to Cloudflare Workers |
vinext lint |
| Delegates to eslint/oxlint |
Use "use cache" directive instead (Next.js 16 approach) |
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.getPlatformProxy() or custom worker entries for bindings. Use import { env } from "cloudflare:workers" instead. This is the modern pattern and works out of the box with vinext and @cloudflare/vite-plugin.vinext deploy / @cloudflare/vite-plugin provides the best experience with cloudflare:workers bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.