vinext

Run Next.js apps on Vite. Drop-in replacement for the next CLI with Cloudflare Workers deployment.

Experimental — under heavy development. This project is an experiment in AI-driven software development. The vast majority of the code, tests, and documentation were written by AI. Use at your own risk. There will be bugs, rough edges, and things that don’t work.

vinext

The Next.js API surface, reimplemented on Vite.

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.

Quick Start

Get started in 5 minutes with a working vinext app

Installation

Detailed installation and migration guide

CLI Reference

Complete command reference for the vinext CLI

API Coverage

See what Next.js features are supported

Why vinext?

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 is an experiment: can we reimplement the Next.js API surface on Vite, so that existing Next.js applications can run on a completely different toolchain?

The answer, so far, is mostly yes — about 94% of the API surface works.

Key Features

Drop-in Replacement

Replace next with vinext in your scripts. No major code changes required.

Both Routers Supported

Full support for Pages Router and App Router with React Server Components.

Fast HMR

Powered by Vite’s lightning-fast Hot Module Replacement.

Cloudflare Workers

One-command deployment to Cloudflare Workers with vinext deploy.

Zero Config

Auto-detects your project structure. No vite.config.ts needed for basic usage.

Compatible

94% of the Next.js 16 API surface supported, including ISR, middleware, and server actions.

Design Principles

• Start with Cloudflare, expand later. Workers is the current deployment target. Every feature is built and tested for Workers. We’re interested in supporting other platforms and welcome contributions.
• 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.

CLI Commands

vinext provides a complete CLI that mirrors the Next.js command structure:

Command	Description
vinext dev	Start dev server with HMR
vinext build	Production build (multi-environment for App Router: RSC + SSR + client)
vinext start	Start local production server for testing
vinext deploy	Build and deploy to Cloudflare Workers
vinext init	Migrate a Next.js project to run under vinext
vinext check	Scan your Next.js app for compatibility issues before migrating
vinext lint	Delegate to eslint or oxlint

Common Options

• -p / --port <port> — Specify port number
• -H / --hostname <host> — Specify hostname
• --turbopack — Accepted for compatibility (no-op, Vite is always used)

Deploy Options

• --preview — Deploy to a preview environment
• --name <name> — Custom Worker name
• --skip-build — Skip the build step
• --dry-run — Generate config files without building or deploying
• --experimental-tpr — Enable Traffic-aware Pre-Rendering

Init Options

• --port <port> — Dev server port for vinext script (default: 3001)
• --skip-check — Skip the compatibility check step
• --force — Overwrite existing vite.config.ts

API Coverage

~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features and Partial Prerendering (which Next.js 16 reworked into "use cache" — that directive is fully supported).

✅ = full implementation | 🟡 = partial (runtime behavior correct, some build-time optimizations missing) | ⬜ = intentional stub/no-op

Module Shims

Every next/* import is shimmed to a Vite-compatible implementation.

Module	Status	Notes
next/link	✅	All props including prefetch, onNavigate, scroll restoration, basePath, locale
next/image	🟡	Remote images via @unpic/react (28 CDNs). Local images via <img> + srcSet. No build-time optimization/resizing
next/head	✅	SSR collection + client-side DOM manipulation
next/router	✅	useRouter, Router singleton, events, client-side navigation, SSR context, i18n
next/navigation	✅	usePathname, useSearchParams, useParams, useRouter, redirect, notFound, forbidden, unauthorized
next/server	✅	NextRequest, NextResponse, NextURL, cookies, userAgent, after, connection, URLPattern
next/headers	✅	Async headers(), cookies(), draftMode()
next/dynamic	✅	ssr: true, ssr: false, loading component
next/script	✅	All 4 strategies (beforeInteractive, afterInteractive, lazyOnload, worker)
next/font/google	🟡	Runtime CDN loading. No self-hosting, font subsetting, or fallback metrics
next/cache	✅	revalidateTag, revalidatePath, unstable_cache, pluggable CacheHandler, "use cache" with cacheLife() and cacheTag()
next/form	✅	GET form interception + POST server action delegation
next/og	✅	OG image generation via @vercel/og (Satori + resvg)

Routing

Feature	Status	Notes
File-system routing (pages/)	✅	Automatic scanning with hot-reload on file changes
File-system routing (app/)	✅	Pages, routes, layouts, templates, loading, error, not-found, forbidden, unauthorized
Dynamic routes [param]	✅	Both routers
Catch-all [...slug]	✅	Both routers
Optional catch-all [[...slug]]	✅	Both routers
Route groups (group)	✅	URL-transparent, layouts still apply
Parallel routes @slot	✅	Discovery, layout props, default.tsx, inherited slots
Intercepting routes	✅	(.), (..), (..)(..), (...) conventions
Route handlers (route.ts)	✅	Named HTTP methods, auto OPTIONS/HEAD, cookie attachment
Middleware	✅	middleware.ts and proxy.ts (Next.js 16). Matcher patterns
i18n routing	🟡	Pages Router locale prefix, Accept-Language detection, NEXT_LOCALE cookie. No domain-based routing
basePath	✅	Applied everywhere — URLs, Link, Router, navigation hooks
trailingSlash	✅	308 redirects to canonical form

Server Features

Feature	Status	Notes
SSR (Pages Router)	✅	Streaming, _app/_document, __NEXT_DATA__, hydration
SSR (App Router)	✅	RSC pipeline, nested layouts, streaming, nav context for client components
getStaticProps	✅	Props, redirect, notFound, revalidate
getStaticPaths	✅	fallback: false, true, "blocking"
getServerSideProps	✅	Full context including locale
ISR	✅	Stale-while-revalidate, pluggable CacheHandler, background regeneration
Server Actions ("use server")	✅	Action execution, FormData, re-render after mutation, redirect() in actions
React Server Components	✅	Via @vitejs/plugin-rsc. "use client" boundaries work correctly
Streaming SSR	✅	Both routers
Metadata API	✅	metadata, generateMetadata, viewport, generateViewport, title templates
generateStaticParams	✅	With dynamicParams enforcement
Metadata file routes	✅	sitemap.xml, robots.txt, manifest, favicon, OG images (static + dynamic)
Static export (output: 'export')	✅	Generates static HTML/JSON for all routes
connection()	✅	Forces dynamic rendering
"use cache" directive	✅	File-level and function-level. cacheLife() profiles, cacheTag(), stale-while-revalidate
instrumentation.ts	✅	register() and onRequestError() callbacks

What’s NOT Supported

These are intentional exclusions:

• Vercel-specific features — @vercel/og edge runtime, Vercel Analytics integration, Vercel KV/Blob/Postgres bindings. Use platform equivalents.
• AMP — Deprecated since Next.js 13. useAmp() returns false.
• next export (legacy) — Use output: 'export' in config instead.
• Turbopack/webpack configuration — This runs on Vite. Use Vite plugins instead of webpack loaders/plugins.
• next/jest — Use Vitest.
• Bug-for-bug parity with undocumented behavior — If it’s not in the Next.js docs, we probably don’t replicate it.

Known Limitations

• Image optimization doesn’t happen at build time. Remote images work via @unpic/react (auto-detects 28 CDN providers). Local images are routed through a /_vinext/image endpoint.
• Google Fonts are loaded from the CDN, not self-hosted. No size-adjust fallback font metrics. Local fonts work but @font-face CSS is injected at runtime.
• Node.js production server (vinext start) works for testing but is less complete than Workers deployment. Cloudflare Workers is the primary target.

Live Examples

These examples are deployed to Cloudflare Workers and updated on every push to main:

App Router Playground

Vercel’s Next.js App Router Playground running on vinext

Hacker News

HN clone (App Router, RSC)

Nextra Docs

Nextra docs site (MDX, App Router)

RealWorld API

REST API routes example

Alternatives

Worth knowing about:

• OpenNext — adapts next build output for AWS, Cloudflare, and other platforms. More mature and battle-tested than vinext.
• Next.js self-hosting — Next.js can be deployed to any Node.js server, Docker container, or as a static export.

Can I Use This in Production?

You can, with caution. This is experimental software with known bugs. It works well enough for demos and exploration, but it hasn’t been battle-tested with real production traffic. The test suite has over 1,700 Vitest tests and 380 Playwright E2E tests, but human code review is minimal — this is an experiment in AI-driven development.

Next Steps

Quick Start

Get started in 5 minutes

Installation Guide

Migrate an existing Next.js project