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

devDependencies

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

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/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:

tsx

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:

bash

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:

bash

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.

migrate-to-vinext

NPX Install

Tags

SKILL.md Content

Migrate Next.js to vinext

FIRST: Verify Next.js Project

Quick Reference

Phase 1: Check Compatibility

Phase 2: Automated Migration (Recommended)

Phase 3: Manual Migration

3a. Replace packages

3b. Update scripts

3c. Convert to ESM

3d. Generate vite.config.ts

Phase 4: Deployment (Optional)

Option A: Cloudflare Workers (recommended for Cloudflare)

Cloudflare Bindings (D1, R2, KV, AI, etc.)

Option B: Other platforms (via Nitro)

Phase 5: Verify

Known Limitations

Anti-patterns