migrate-to-vinext

$29

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

Phase 2: Automated Migration (Recommended)

Run vinext init. This command:

• Runs vinext check for a compatibility report

• Installs vite as a devDependency (and @vitejs/plugin-rsc for App Router)

• Adds "type": "module" to package.json

• Renames CJS config files (e.g., postcss.config.js → .cjs) to avoid ESM conflicts

• Adds dev:vinext and build:vinext scripts to package.json

• 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

# 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/oxlint

Preserve flags: next dev --port 3001 → vinext dev --port 3001.

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.

Phase 4: Deployment (Optional)

Option A: Cloudflare Workers (recommended for Cloudflare)

If the user wants to deploy to Cloudflare Workers, use 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.

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

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, 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 (vinext deploy / @cloudflare/vite-plugin) is recommended for the best developer experience with cloudflare:workers bindings, KV caching, and one-command deploys.

Phase 5: Verify

• Run vinext dev to start the development server

• Confirm the server starts without errors

• Navigate key routes and check functionality

• 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

Route segment configs ignored

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