--- title: "migrate-to-vinext by cloudflare · skilld" canonical_url: "https://skilld.dev/gh/cloudflare/vinext" meta: description: "Migrates Next.js projects to vinext, a Vite-based reimplementation of Next.js that runs existing app/ and pages/ directories without code changes. Handles compatibility… From cloudflare/vinext." "og:description": "Migrates Next.js projects to vinext, a Vite-based reimplementation of Next.js that runs existing app/ and pages/ directories without code changes. Handles compatibility… From cloudflare/vinext." "og:title": "migrate-to-vinext by cloudflare" "twitter:description": "Migrates Next.js projects to vinext, a Vite-based reimplementation of Next.js that runs existing app/ and pages/ directories without code changes. Handles compatibility… From cloudflare/vinext." "twitter:title": "migrate-to-vinext by cloudflare" --- ` [All skills](https://skilld.dev/skills) [![cloudflare avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fcloudflare.png%3Fsize%3D96)](https://skilld.dev/gh/cloudflare) # **/migrate-to-vinext** [@115771d](https://github.com/cloudflare/vinext/commit/115771d869bc51913f62ad5edb4845cba1a5f3b3 "Your agent reads SKILL.md at commit 115771d") by [cloudflare](https://skilld.dev/gh/cloudflare)· [cloudflare](https://skilld.dev/gh/cloudflare)/ [vinext](https://skilld.dev/gh/cloudflare/vinext)·9.1k stars 427 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 platforms via Nitro). - 4 files - 29 KB - Updated 3 days ago - [GitHub](https://github.com/cloudflare/vinext/blob/115771d869bc51913f62ad5edb4845cba1a5f3b3/.agents/skills/migrate-to-vinext/SKILL.md "View SKILL.md on GitHub") - [No alerts](#third-party-checks "Third-party checks: No alerts · 5 checks · Risk SAFE") ## SKILL.md 10.7 KB **≈84** tokens always: the name and description. **≈2.6k** when used: this file. **≈4.7k** more on demand in 3 files. ## 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](https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext/-/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 ``` # Example with npm: npm uninstall next npm install vinext npm install -D vite # App Router only: npm install -D @vitejs/plugin-rsc ``` #### 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](https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext/-/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):** ``` 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. #### 3e. Update .gitignore Ensure vinext-generated output and caches are ignored: ``` /dist/ .vinext/ ``` ### 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](https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext/-/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: ``` import { env } from "cloudflare:workers"; export default async function Page() { const result = await env.DB.prepare("SELECT * FROM posts").all(); return
{JSON.stringify(result)}
; } ``` 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: ``` 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 (`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](https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext/-/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. Source: [SKILL.md on GitHub](https://github.com/cloudflare/vinext/blob/115771d869bc51913f62ad5edb4845cba1a5f3b3/.agents/skills/migrate-to-vinext/SKILL.md) ## Third-party checks
No alerts3d5 checks · Risk SAFE - Gen Agent Trust Hub3d This skill provides a guided process for migrating web projects to a new build system and framework. It utilizes standard developer workflows, including automated package management and command execution for building and deploying applications. These operations are appropriate for the skill's stated purpose of project migration. - Socket3d No alerts - Snyk3d Risk: LOW · No issues - Runlayer6mo 4 files scanned · No issues - ZeroLeaks5mo Score: 93/100 · 2 sections analyzed
## Provenance [Signed by skilld at 115771d.](https://github.com/cloudflare/vinext/commit/115771d869bc51913f62ad5edb4845cba1a5f3b3 "115771d869bc51913f62ad5edb4845cba1a5f3b3") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions. Last checked against GitHub 2 hours ago. Activeupdated 3 days ago ## Topics - [Next.js](https://skilld.dev/frameworks/nextjs "Next.js app router, server components, routing") - vite - vinext - migration - cloudflare - workers - esm - app-router - pages-router - nitro ## README badge ![README badge for cloudflare/vinext](https://skilld.dev/b/cloudflare/vinext?theme=light&label=0) ## What it does Migrates Next.js projects to vinext, a Vite-based reimplementation of Next.js that runs existing app/ and pages/ directories without code changes. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment to Cloudflare Workers or other platforms via Nitro. Generated from the current SKILL.md. ## Frequently asked
Do I need to rewrite my app/ or pages/ directory? No. vinext reimplements the Next.js API surface on Vite, so existing \`app/\`, \`pages/\`, and \`next.config.js\` work as-is without code changes.
What package managers does this support? The skill detects and works with npm, pnpm, yarn, and bun based on the lockfile present in the project.
Can I deploy to platforms other than Cloudflare? Yes. For Vercel, Netlify, AWS, Deno Deploy, and other platforms, add the Nitro Vite plugin and set the appropriate NITRO\_PRESET during build. For Cloudflare Workers specifically, the native \`vinext deploy\` integration is recommended.
How do I access Cloudflare bindings like D1, R2, or KV? Use \`import { env } from "cloudflare:workers"\` in server components or route handlers. Bindings must be defined in \`wrangler.jsonc\`, and this approach works out of the box with vinext and \`@cloudflare/vite-plugin\`.
What happens if vinext init fails? The skill provides a manual migration path (Phase 3) that covers package replacement, script updates, ESM conversion, and Vite config generation as a fallback.
Generated from the current SKILL.md. These answers refresh after source changes. ## Related skills - - - - - -