vinext

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

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: runtime and preferredRegion route config are currently ignored, 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

vinext includes an Agent Skill that handles migration for you. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools. Install it, open your Next.js project, and tell the AI to migrate:

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

Replace next with vinext in your scripts:

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

vinext dev          # Development server with HMR
vinext 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.

vinext auto-detects your app/ or pages/ directory, loads next.config.js, and configures Vite automatically. No vite.config.ts required for basic usage.

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

Options: -p / --port <port>, -H / --hostname <host>, --turbopack (accepted, no-op).

@vinext/cloudflare deploy options: --preview, --env <name>, --name <name>, --skip-build, --dry-run, --experimental-tpr.

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.

If your next.config.* sets output: "standalone", vinext 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.

Starting a new vinext project

Use create-vinext-app for new projects. It creates a TypeScript App Router project with Tailwind CSS and then runs the same vinext init setup used for existing apps:

pnpm create vinext-app@latest my-app

The generated project is Cloudflare Workers-ready by default. Pass --platform=node if you want the Node target instead.

Migrating an existing Next.js project

vinext init automates the migration in one command:

npx vinext init

This will:

1. Run vinext check to scan for compatibility issues
2. Install vinext runtime packages as dependencies and Vite/plugin tooling as devDependencies
3. Rename CJS config files (e.g. postcss.config.js -> .cjs) to avoid ESM conflicts
4. Add "type": "module" to package.json
5. Add dev:vinext, build:vinext, and start:vinext scripts to package.json
6. Prompt for a deployment platform (Cloudflare by default, or Node)
7. Generate the matching vite.config.ts
8. For Cloudflare, generate wrangler.jsonc

The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify next.config, tsconfig.json, or any source files, and it does not remove Next.js dependencies.

vinext targets Vite 8, which defaults to Rolldown, Oxc, Lightning CSS, and a newer browser baseline. If you bring custom Vite config or plugins from an older setup, prefer oxc, optimizeDeps.rolldownOptions, and build.rolldownOptions over older esbuild and build.rollupOptions knobs, and override build.target if you still need older browsers. If a dependency breaks because of stricter CommonJS default import handling, fix the import or use legacy.inconsistentCjsInterop: true as a temporary escape hatch. See the Vite 8 migration guide.

npm run dev:vinext    # Start the vinext dev server (port 3001)
npm run build:vinext  # Build production output with vinext
npm run start:vinext  # Start vinext production server
npm run dev           # Still runs Next.js as before

Use --platform=cloudflare or --platform=node to skip the platform prompt. Cloudflare init updates an existing JavaScript or TypeScript Vite config using its AST, preserving unrelated settings. Use --force to replace an existing Node-target Vite config, or --skip-check to skip the compatibility report.

Why

Vite has become the default build tool for modern web frameworks — fast HMR, a clean plugin API, native ESM, and a growing ecosystem. With @vitejs/plugin-rsc adding React Server Components support, it's now possible to build a full RSC framework on Vite.

vinext reimplements the Next.js API surface on Vite so existing Next.js applications can run on a different toolchain. The answer, so far, is that substantial applications can.

vinext works everywhere. It natively supports Cloudflare Workers (with npx @vinext/cloudflare deploy or vp exec vinext-cloudflare deploy, bindings, KV caching), and can be deployed to Vercel, Netlify, AWS, Deno Deploy, and more via the Nitro Vite plugin. Native support for additional platforms is planned.

Alternatives worth knowing about:

• OpenNext — adapts next build output for AWS, Cloudflare, and other platforms. OpenNext has been around much longer than vinext, is more mature, and covers more of the Next.js API surface because it builds on top of Next.js's own output rather than reimplementing it. If you want the safer, more proven option, start there.
• Next.js self-hosting — Next.js can be deployed to any Node.js server, Docker container, or as a static export.

Design principles

• Deploy anywhere. Natively supports Cloudflare Workers, with other platforms available via Nitro. Native adapters for more platforms are planned.
• Pragmatic compatibility, not bug-for-bug parity. Targets 95%+ of real-world Next.js apps. Edge cases that depend on undocumented Vercel behavior are intentionally not supported.
• Latest Next.js only. Targets Next.js 16.x. No support for deprecated APIs from older versions.
• Incremental adoption. Drop in the plugin, fix what breaks, deploy.

FAQ

What is this? vinext is a Vite plugin that reimplements the public Next.js API — routing, server rendering, next/* module imports, the CLI — so you can run Next.js applications on Vite instead of the Next.js compiler toolchain. It can be deployed anywhere: Cloudflare Workers is the first natively supported target, with other platforms available via Nitro. Native adapters for more platforms are planned.

Is this a fork of Next.js? No. vinext is an alternative implementation of the Next.js API surface built on Vite. It does import some Next.js types and utilities, but the core is written from scratch. The goal is not to create a competing framework or add features beyond what Next.js offers; it is to provide the same well-defined API surface on Vite's toolchain.

How is this different from OpenNext? OpenNext adapts the output of a standard next build to run on various platforms. Because it builds on Next.js's own output, it inherits broad API coverage and has been well-tested for much longer. vinext takes a different approach: it reimplements the Next.js APIs on Vite from scratch, which means faster builds and smaller bundles, but less coverage of the long tail of Next.js features. If you need a mature, well-tested way to run Next.js outside Vercel, OpenNext is the safer choice. If you want a lighter Vite-based toolchain and do not need every Next.js API, vinext may be a good fit.

Can I use this in production? You can, with caution. vinext has known compatibility gaps and has not yet been battle-tested across the full range of production Next.js workloads. Evaluate the features and deployment target your application relies on before adopting it.

Can I just self-host Next.js? Yes. Next.js supports self-hosting on Node.js servers, Docker containers, and static exports. If you're happy with the Next.js toolchain and just want to run it somewhere other than Vercel, self-hosting is the simplest path.

How are you verifying this works? The test suite has over 1,700 Vitest tests and 380 Playwright E2E tests. This includes tests ported directly from the Next.js test suite and OpenNext's Cloudflare conformance suite, covering routing, SSR, RSC, server actions, caching, metadata, middleware, streaming, and more. Vercel's App Router Playground also runs on vinext as an integration test. See the Tests section and tests/nextjs-compat/TRACKING.md for details.

Who is reviewing this code? A mix of humans and AI agents. Human