vinext

Run Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.

Website: vinext.dev

Documentation: vinext.dev/docs

Read the announcement: How we rebuilt Next.js with AI in one week

Under active development. vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.

vinext reimplements the Next.js API surface on Vite rather than consuming next build output. It supports both the App Router and Pages Router, React Server Components, Server Actions, middleware, route handlers, ISR, static export, and the most commonly used next/* modules. Cloudflare Workers has the deepest integration; Node.js and other platforms are available with different levels of support.

Project status

What works today

• App Router and Pages Router in development and production builds
• React Server Components, Server Actions, route handlers, and middleware
• Static generation, ISR, output: "export", and standalone Node.js output
• Core Next.js APIs and modules, including next/link, next/image, next/navigation, next/headers, next/cache, and the Metadata API
• Cloudflare Workers deployment with bindings, cache adapters, and image optimization support
• Migration tooling through vinext check, vinext init, and the vinext Agent Skill

Known gaps we're working on

These are active compatibility areas, not permanent exclusions:

• Cache Components and Partial Prerendering: "use cache" is partially implemented, but full cacheComponents behavior is still incomplete. Cache profiles, tags, partial shells, resume behavior, prefetching, and some dev/build cache semantics do not yet match Next.js in every case.
• Build-time image and font optimization: images can be optimized at request time on Cloudflare, but vinext does not yet reproduce Next.js's complete build-time image pipeline. Google Fonts are loaded from the CDN, and local font CSS is injected at runtime rather than extracted during the build.
• Native modules in App Router development: packages such as sharp, resvg, satori, lightningcss, and @napi-rs/canvas can fail in Vite's RSC development environment. Production builds support more of these cases than development mode.
• Platform-specific and advanced Next.js behavior: preferredRegion route config is ignored, and runtime doesn't choose where a route runs (outside cacheComponents, a runtime = "edge" App Router page is never ISR-cached, as in Next.js), and some recently introduced or undocumented Next.js behavior may not yet be reproduced.

Run vinext check against an existing application before migrating. If a gap is not listed here, check the open issues or file a focused reproduction.

Quick start

Use the official setup commands below. They are the recommended way to create or migrate a vinext project because they configure dependencies, scripts, Vite, and your deployment target for you.

Start a new project with create-vinext-app:

pnpm create vinext-app@latest my-app

Migrate an existing Next.js project with vinext init:

npx vinext init

Optional: migrate with an AI agent

Prefer vinext init for a direct, repeatable migration. If you want an AI agent to investigate compatibility issues and guide the migration, vinext also includes an optional Agent Skill. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools:

npx skills add cloudflare/vinext

Then open your Next.js project in any supported tool and say:

migrate this project to vinext

The skill handles compatibility checking, dependency installation, config generation, and dev server startup. It knows what vinext supports and will flag anything that needs manual attention.

Or do it manually

npm install vinext
npm install -D vite @vitejs/plugin-react

If you're using the App Router, also install:

npm install react-server-dom-webpack
npm install -D @vitejs/plugin-rsc

Add a Vite config:

import { defineConfig } from "vite";
import vinext from "vinext";

export default defineConfig({
  plugins: [vinext()],
});

Then use Vite for development and builds:

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "vinext start"
  }
}

npx vite dev        # Development server with HMR
npx vite build      # Production build
npx @vinext/cloudflare deploy  # Build and deploy to Cloudflare Workers

With Vite+, use vpx @vinext/cloudflare deploy, or vp exec vinext-cloudflare deploy when running the locally installed bin.

The vinext() plugin auto-detects your app/ or pages/ directory and loads next.config.js.

Your existing pages/, app/, next.config.js, and public/ directories work as-is. Run vinext check first to scan for known compatibility issues, or use vinext init to automate the full migration.

CLI reference

vinext dev and vinext build remain as thin aliases for the project-local Vite commands. They require a Vite config; if one is missing, run vinext init. Vite owns their options, output, and exit behavior. For older configured projects, the aliases still preload dotenv before Vite evaluates the config and add "type": "module" (renaming known CommonJS config files to .cjs) when an unambiguous default Vite config requires the ESM migration. An explicit "type": "commonjs" is never changed. Direct vite dev and vite build do not perform these wrapper compatibility steps.

@vinext/cloudflare deploy options: --preview, --env <name>, --name <name>, --vite-config <path>, --skip-build, --dry-run, --warm-cache, --traffic-aware-warm-cache.

vinext init prompts for a deployment target, defaulting to Cloudflare. Agents must ask the user which target they want, then pass --platform=cloudflare or --platform=node.

Other options: --port <port> (default: 3001), --skip-check, --force.

Cloudflare init uses cf and cloudflare.config.ts by default. Both vinext init and create-vinext-app accept --legacy-wrangler-cloudflare-init to retain the legacy Wrangler setup. Existing Wrangler configs are not automatically migrated. If a root Wrangler config belongs to another Worker, vinext init --ignore-wrangler-config sets up cloudflare.config.ts and leaves that file untouched. vinext init --name <name> sets the Worker name in the generated config instead of deriving it from package.json. An existing config keeps its own Worker name, and init prints a warning.

If your next.config.* sets output: "standalone", vite build emits a self-hosting bundle at dist/standalone/. Start it with:

node dist/standalone/server.js

Environment variables: PORT (default 3000), HOST (default 0.0.0.0).

Note: Next.js standalone uses HOSTNAME for the bind address, but vinext uses HOST to avoid collision with the system-set HOSTNAME variable on Linux. Update your deployment config accordingly.

Custom standalone entries

The generated server.js is a small wrapper around startProdServer from vinext/server/prod-server. To control where the server loads the build output from, write your own entry and call startProdServer directly. All options are optional: