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.
Overview
vinext implements approximately 94% of the Next.js 16 API surface with full or partial support. The remaining gaps are intentional stubs for deprecated features and edge cases.
Legend:
- ✅ = 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.
Core Modules
| Module | Status | Notes |
|---|
next/link | ✅ | All props including prefetch (IntersectionObserver), 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) |
Fonts and Assets
| Module | Status | Notes |
|---|
next/font/google | 🟡 | Runtime CDN loading. No self-hosting, font subsetting, or fallback metrics |
next/font/local | 🟡 | Runtime @font-face injection. Not extracted at build time |
next/og | ✅ | OG image generation via @vercel/og (Satori + resvg) |
Cache and State
| Module | Status | Notes |
|---|
next/cache | ✅ | revalidateTag, revalidatePath, unstable_cache, pluggable CacheHandler, "use cache" with cacheLife() and cacheTag() |
next/form | ✅ | GET form interception + POST server action delegation |
Legacy and Utility
| Module | Status | Notes |
|---|
next/legacy/image | ✅ | Translates legacy props to modern Image |
next/error | ✅ | Default error page component |
next/config | ✅ | getConfig / setConfig |
next/document | ✅ | Html, Head, Main, NextScript |
next/constants | ✅ | All phase constants |
next/amp | ⬜ | No-op (AMP is deprecated) |
next/web-vitals | ⬜ | No-op (use the web-vitals library directly) |
Routing Features
| 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 (string, array, regex, :param, :path*, :path+) |
| 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
Rendering
| 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 |
| React Server Components | ✅ | Via @vitejs/plugin-rsc. "use client" boundaries work correctly |
| Streaming SSR | ✅ | Both routers |
Static export (output: 'export') | ✅ | Generates static HTML/JSON for all routes |
Data Fetching
| Feature | Status | Notes |
|---|
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 |
"use cache" directive | ✅ | File-level and function-level. cacheLife() profiles, cacheTag(), stale-while-revalidate |
| Feature | Status | Notes |
|---|
| Metadata API | ✅ | metadata, generateMetadata, viewport, generateViewport, title templates |
| Metadata file routes | ✅ | sitemap.xml, robots.txt, manifest, favicon, OG images (static + dynamic) |
generateStaticParams | ✅ | With dynamicParams enforcement |
Other Server Features
| Feature | Status | Notes |
|---|
connection() | ✅ | Forces dynamic rendering |
instrumentation.ts | ✅ | register() and onRequestError() callbacks |
| Route segment config | 🟡 | revalidate, dynamic, dynamicParams. runtime and preferredRegion are ignored |
Configuration
| Feature | Status | Notes |
|---|
next.config.js / .ts / .mjs | ✅ | Function configs, phase argument |
rewrites / redirects / headers | ✅ | All phases, param interpolation |
Environment variables (NEXT_PUBLIC_*) | ✅ | Inlined at build time via Vite |
images config | 🟡 | Parsed but not used for optimization |
Caching
The cache is pluggable. The default MemoryCacheHandler works out of the box. For production, use a custom backend:
import { setCacheHandler } from "next/cache";
import { KVCacheHandler } from "vinext/cloudflare";
setCacheHandler(new KVCacheHandler(env.MY_KV_NAMESPACE));
CacheHandler interface matches Next.js 16’s shape, so community adapters should be compatible.
Test Coverage
vinext’s API compatibility is verified by:
- 1,700+ Vitest tests — Unit and integration tests
- 380+ Playwright E2E tests — Browser-based testing
- Tests ported from Next.js — Direct compatibility verification
- OpenNext conformance suite — Cloudflare deployment behavior
See the test tracking document for detailed results.