Migrate To Vinext
Convert an existing Next.js app to vinext on Vite while keeping app/, pages/, and next.config.js unchanged, then ship to Cloudflare Workers or Nitro-backed hosts.
Overview
Migrate-to-vinext is an agent skill most often used in Build (also Ship) that migrates Next.js projects to the Vite-based vinext reimplementation via compatibility scan, package swap, config generation, and deployment se
Install
npx skills add https://github.com/cloudflare/vinext --skill migrate-to-vinextWhat is this skill?
- Hard gate: stops unless `next` appears in package.json dependencies or devDependencies
- Detects pnpm, yarn, bun, or npm from lockfiles and uses the matching add/remove commands
- Distinguishes App Router (`app/`) vs Pages Router (`pages/`) including both coexisting
- Runs compatibility scanning, vinext package replacement, Vite config generation, and ESM conversion without app rewrites
- Deployment paths: Cloudflare Workers natively and other platforms via Nitro
- 4 package-manager lockfile variants mapped to install/uninstall commands
- 2 router modes detected: App Router (`app/`) and Pages Router (`pages/`)
Adoption & trust: 3.6k installs on skills.sh; 8.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want Vite-speed builds and Cloudflare-friendly deploys but your app is still locked to the Next.js package and you do not want to rewrite `app/` or `pages/` routes.
Who is it for?
Solo builders with an existing App or Pages Router Next.js repo who explicitly want vinext and can run a guided package-and-config migration.
Skip if: Repos without `next` in package.json, greenfield apps with no Next.js code to preserve, or teams that need to stay on official Next.js with zero toolchain change.
When should I use this skill?
User asks to migrate, convert, or switch from Next.js to vinext.
What do I get? / Deliverables
After the skill runs you have vinext installed, generated Vite/ESM tooling, and a documented deploy path (Workers or Nitro) without changing application code.
- Updated dependencies with vinext
- Generated Vite configuration and ESM project layout
- Deployment setup notes for Workers or Nitro targets
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is build/integrations because the skill is a full toolchain swap (packages, Vite config, ESM) before production cutover. Migration wires Next.js APIs to Vite, package managers, and deployment adapters—not a greenfield UI or backend feature.
Where it fits
Replace `next` with vinext and generate Vite config after detecting App Router from `src/app/`.
Configure Cloudflare Workers deployment once the vinext build succeeds locally.
How it compares
Use for a guided Next→vinext package migration instead of hand-rolling Vite config and guessing API compatibility.
Common Questions / FAQ
Who is migrate-to-vinext for?
Indie and solo developers shipping Next.js apps who want vinext on Vite—especially when targeting Cloudflare Workers—without rewriting route files.
When should I use migrate-to-vinext?
Use it during Build when swapping the framework toolchain, and during Ship when you need Workers or Nitro deployment wiring after the code-compatible migration steps finish.
Is migrate-to-vinext safe to install?
Review the Security Audits panel on this Prism page and inspect what the agent will run locally (package installs, config writes) before executing on a production branch.
SKILL.md
READMESKILL.md - Migrate To Vinext
# 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 | | `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 | ## 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` 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 ```bash # 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` | `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/ox