Name: migrate-to-vinext
Author: cloudflare

Migrates Next.js projects to vinext (Vite-based Next.js reimplementation). Load when asked to migrate, convert, or switch from Next.js to vinext. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup (Cloudflare Workers natively, other plat

Migrate Next.js to 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. FIRST: Verify Next.js Project 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 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. 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 npx vite dev Development server with HMR npx vite build Production build (multi environment for App Router) vinext start Local production server npx @vinext/cloudflare deploy Build and deploy to Cloudflare Workers vp exec vinext cloudflare deploy Build and deploy to Cloudflare Workers with Vite+ Phase 1: Check Compatibility 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](references/compatibility.md) for supported/unsupported features and ecosystem library status. Phase 2: Automated Migration (Recommended) Run vinext init . This command: 1. Runs vinext check for a compatibility report 2. Installs vite as a devDependency (and @vitejs/plugin rsc for App Router) 3. Adds "type": "module" to package.json 4. Renames CJS config files (e.g., postcss.config.js → .cjs ) to avoid ESM conflicts 5. Adds dev:vinext and build:vinext scripts to package.json 6. Generates a minimal vite.config.ts 7. Adds /dist/ and .vinext/ to .gitignore 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. If vinext init succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3. Phase 3: Manual Migration Use this as a fallback when vinext init doesn't work or the user wants full control. 3a. Replace packages 3b. Update scripts Replace all next commands in package.json scripts: Before After Notes next dev vite dev Dev server with HMR next build vite build Production build next start vinext start Local production server next lint vinext lint Delegates to eslint/oxlint Preserve Vite compatible flags: next dev port 3001 → vite dev port 3001 . Translate Next only build flags into vinext() options in vite.config.ts instead of forwarding them to Vite. 3c. Convert to 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 3d. Generate vite.config.ts See [references/config examples.md](references/config examples.md) for config variants per router and deployment target. If the project already has custom Vite config, prefer Vite 8 native keys when editing it: oxc , optimizeDeps.rolldownOptions , and build.rolldownOptions . Older esbuild and build.rollupOptions settings still work for now but are migration targets. Pages Router (minimal): App Router (minimal): 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. 3e. Update .gitignore Ensure vinext generated output and caches are ignored: Phase 4: Deployment (Optional) Option A: Cloudflare Workers (recommended for Cloudflare) If the user wants to deploy to Cloudflare Workers, use npx @vinext/cloudflare deploy . With Vite+, use vp exec vinext cloudflare deploy when running the locally installed bin. It builds and deploys via wrangler. For manual setup or custom worker entries, see [references/config examples.md](references/config examples.md). Cloudflare Bindings (D1, R2, KV, AI, etc.) 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: 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. Option B: Other platforms (via Nitro) For deploying to Vercel, Netlify, AWS, Deno Deploy, or any other [Nitro supported platform](https://v3.nitro.build/deploy), add the Nitro Vite plugin: Build and deploy: 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 ( npx @vinext/cloudflare deploy / vp exec vinext cloudflare deploy / @cloudflare/vite plugin ) is recommended for the best developer experience with cloudflare:workers bindings, KV caching, and one command deploys. Phase 5: Verify 1. Run the generated dev:vinext script (or npx vite dev ) to start the development server 2. Confirm the server starts without errors 3. Navigate key routes and check functionality 4. Report the result to the user — if errors occur, share full output See [references/troubleshooting.md](references/troubleshooting.md) for common migration errors. 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 Placement ignored; edge App Router pages skip ISR outside cacheComponents PPR (Partial Prerendering) Use "use cache" directive instead (Next.js 16 approach) 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. Do not use 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 . For Cloudflare Workers, prefer the native integration over Nitro. npx @vinext/cloudflare deploy / vp exec vinext cloudflare 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.