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.
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
Everynext/* 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: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/imageendpoint. - Google Fonts are loaded from the CDN, not self-hosted. No
size-adjustfallback font metrics. Local fonts work but@font-faceCSS 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 tomain:
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 buildoutput 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?
Next Steps
Quick Start
Get started in 5 minutes
Installation Guide
Migrate an existing Next.js project