API Coverage

Complete Next.js 16 API compatibility matrix for vinext

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

Metadata

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));

The 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.

For features not supported, see the Known Limitations page.