> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cloudflare/vinext/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Get started in 5 minutes with a working vinext app
Detailed installation and migration guide
Complete command reference for the vinext CLI
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`](https://github.com/vitejs/vite-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
Replace `next` with `vinext` in your scripts. No major code changes required.
Full support for Pages Router and App Router with React Server Components.
Powered by Vite's lightning-fast Hot Module Replacement.
One-command deployment to Cloudflare Workers with `vinext deploy`.
Auto-detects your project structure. No `vite.config.ts` needed for basic usage.
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 ` — Specify port number
* `-H / --hostname ` — Specify hostname
* `--turbopack` — Accepted for compatibility (no-op, Vite is always used)
### Deploy Options
* `--preview` — Deploy to a preview environment
* `--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 ` — 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 `![]()
` + 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`:
Vercel's Next.js App Router Playground running on vinext
HN clone (App Router, RSC)
Nextra docs site (MDX, App Router)
REST API routes example
## Alternatives
**Worth knowing about:**
* **[OpenNext](https://opennext.js.org/)** — adapts `next build` output for AWS, Cloudflare, and other platforms. More mature and battle-tested than vinext.
* **[Next.js self-hosting](https://nextjs.org/docs/app/building-your-application/deploying#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
Get started in 5 minutes
Migrate an existing Next.js project