Migrates Next.js projects to vinext (Vite-based Next.js reimplementation for Cloudflare Workers). Load when asked to migrate, convert, or switch from Next.js to vinext. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and Cloudflare deployment setup.
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.lockbbun.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.
| 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 |
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 | vinext lint | Delegates to eslint/oxlint |
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, 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.
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) | Use "use cache" directive instead (Next.js 16 approach) |
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.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.