Index of every page on this site: llms.txt
All skills
cloudflare avatar

/migrate-to-vinext

@117e752
by cloudflarecloudflare/vinext9.4k stars
481
Run it yourself

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).

Use this Skill: https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈84 tokens for metadata: the name and description. ≈4.7k when used: this file. ≈5.4k more on demand in 3 files.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈337 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 for supported/unsupported features and ecosystem library status.

Phase 2: Automated Migration (Recommended)

Ask the user which deployment target they want (Cloudflare Workers or Node), then pass it with --platform. For Cloudflare, also ask for the cache and image choices below. vinext init prompts for them only in an interactive terminal: agents and CI must pass all three of --cdn-cache, --data-cache, and --image-optimization, and in an agent session init errors out without them. Do not pick a choice for the user.

npx vinext init --platform=node
npx vinext init --platform=cloudflare --cdn-cache=none --data-cache=none --image-optimization=none --no-prerender

Cloudflare init flags

Flag Values Meaning
--cdn-cache none, response-store, workers-cache, static-assets, data-cache Response cache. none: no shared cache. response-store: Workers Response Store, which also handles data. workers-cache: Workers Cache. static-assets: read-only build-time prerender. data-cache: responses and data both in KV
--response-store-mode service-binding (default), self-contained Only with --cdn-cache=response-store. service-binding runs the cache in a separate Worker deployed with deploy:response-store; self-contained adds its bindings to the app Worker
--data-cache kv, none Data cache for fetch, unstable_cache, and "use cache". Must be none with --cdn-cache=none or response-store, and kv with --cdn-cache=data-cache
--image-optimization cloudflare-images, none cloudflare-images adds imagesOptimizer() and an IMAGES binding; none configures no optimizer
--prerender / --no-prerender flag Prerender all static routes at build time. Unless the app is a static export (output: "export"), Cloudflare deploys serve them only with static-assets, which always prerenders and rejects --no-prerender; with other caches, prefer cache warming
--warm-cache / --no-warm-cache flag Add --warm-cache to the deploy script, which fills the cache before a new version gets traffic. Usually a better fit than --prerender on Cloudflare. Requires a --cdn-cache other than none
--name <name> Worker name Worker name for the generated config (default: derived from package.json)

Example with Workers Response Store and Cloudflare Images:

npx vinext init --platform=cloudflare --cdn-cache=response-store --response-store-mode=service-binding --data-cache=none --image-optimization=cloudflare-images --no-prerender --no-warm-cache

Other options: --port <port> (dev script port, default 3001), --skip-check, --no-install (add dependency entries without installing), --force (Node: overwrite an existing vite.config.ts).

What init does

  1. Runs vinext check for a compatibility report (skip with --skip-check)
  2. Adds "type": "module" to package.json and renames CJS config files (e.g., postcss.config.js → .cjs) to avoid ESM conflicts
  3. Adds dev:vinext (vite dev --port 3001), build:vinext (vite build), and start:vinext scripts. start:vinext is vinext start for Node and vite preview for Cloudflare. Cloudflare also gets deploy:vinext (vinext-cloudflare deploy), plus deploy:response-store in Response Store service-binding mode
  4. Generates vite.config.ts. For Node, an existing Vite config is kept unless you pass --force. For Cloudflare, init updates an existing Vite config instead, adding the cloudflare() plugin and the selected cache and image adapters, and generates cloudflare.config.ts (Worker name, entrypoint, assets routing, and bindings) if it does not exist. With an existing Cloudflare setup, init keeps an existing cloudflare.config.ts and any cache adapters already in the Vite config, and stops with an error for some choices (such as Static Assets, or Response Store service-binding without its wiring). After init, check both files against the complete setup for the chosen cache in Caching on Cloudflare, and follow any error init prints.
  5. Adds /dist/ and .vinext/ to .gitignore, plus .cloudflare/ for Cloudflare
  6. Installs vinext, vite, and @vitejs/plugin-react. App Router adds react-server-dom-webpack and @vitejs/plugin-rsc. Cloudflare adds @vinext/cloudflare, @cloudflare/vite-plugin (v2 beta), and cf, plus @cloudflare/workers-response-store in Response Store service-binding mode

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.

Existing Wrangler config

Cloudflare init stops if the project root already has wrangler.toml, wrangler.json, wrangler.jsonc, or wrangler.response-store.jsonc, because it does not migrate them. Ask the user which way to go:

  • Move its bindings to cloudflare.config.ts, remove the Wrangler config, and rerun init.
  • If the Wrangler config belongs to an unrelated Worker, pass --ignore-wrangler-config. Init sets up cloudflare.config.ts and leaves that file untouched.
  • Legacy: pass --legacy-wrangler-cloudflare-init to keep a Wrangler setup. Init then updates an existing wrangler.jsonc or wrangler.json in place, or generates wrangler.jsonc (it rejects wrangler.toml), installs @cloudflare/vite-plugin@1 and wrangler, ignores .wrangler/, and uses wrangler dev --config dist/server/wrangler.json and vinext-cloudflare deploy --config dist/server/wrangler.json as the start and deploy scripts. Use it only when the user wants to stay on Wrangler. The rest of this skill covers only the cf setup, so point legacy users to the Wrangler documentation for auth, bindings, and types.

If vinext init succeeds, skip Phase 3 and continue with Phase 4 (Deployment) or Phase 5 (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 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)

Set the project up first with vinext init --platform=cloudflare and the flags from Phase 2. It installs cf and Cloudflare Vite plugin v2 and generates cloudflare.config.ts, which is the deployment source of truth. Commit vite.config.ts and cloudflare.config.ts; the generated Build Output under .cloudflare/ stays gitignored.

Authenticate with npx cf auth login. In CI, use a CLOUDFLARE_API_TOKEN instead of browser login. Set the account with accountId at the top level of defineConfig in cloudflare.config.ts (outside worker), or with CLOUDFLARE_ACCOUNT_ID.

Deploy with the generated deploy:vinext script or npx @vinext/cloudflare deploy. With Vite+, use vp exec vinext-cloudflare deploy when running the locally installed bin. It validates the setup, builds, and deploys the application Worker with cf. In Response Store service-binding mode, build and run deploy:response-store before the first application deploy; vinext-cloudflare deploy deploys only the application Worker.

For manual setup or custom worker entries, see 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 <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.

Define each binding in the Worker's env in cloudflare.config.ts, using bindings from cf/config:

import { bindings } from "cf/config";

env: {
  // ...existing bindings
  DB: bindings.d1({ name: "my-db" }),
  CACHE: bindings.kv(),
},

For TypeScript, add .cloudflare/types to the include list in tsconfig.json. Binding and runtime types are generated there during dev and build; run cf workers types before a standalone type-check.

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, 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 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 run Cloudflare init without its choices, or choose them for the user. Ask the user, then pass --cdn-cache, --data-cache, and --image-optimization (plus --response-store-mode for Response Store) explicitly.
  • 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

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts13d5 checks · Risk SAFE
  • Gen Agent Trust Hub14d

    This skill facilitates the migration of Next.js projects to the vinext framework. It includes commands for project scanning, configuration generation, and deployment setup. All identified patterns, including package management and deployment commands, align with its stated purpose as a migration utility.

  • Socket13d

    No alerts

  • Snyk14d

    Risk: LOW · No issues

  • Runlayer8mo

    4 files scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 117e752. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
  • Next.js
  • vite
  • vinext
  • migration
  • cloudflare
  • workers
  • esm
  • app-router
  • pages-router
  • nitro

README badge

README badge for cloudflare/vinext

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.

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.