Skip to main content

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 reimplements the Next.js module API surface using Vite, allowing you to use standard next/* imports with full compatibility.

​
Available Modules

All next/* imports are automatically shimmed by vinext:
ModuleDescriptionRouter Support
next/linkClient-side navigation with prefetchingApp + Pages
next/imageOptimized image componentApp + Pages
next/navigationApp Router navigation hooksApp Router
next/routerPages Router navigationPages Router
next/serverServer-side request/response utilitiesApp + Pages
next/headersServer Component header accessApp Router
next/cacheCaching and revalidationApp Router
next/dynamicCode splitting and lazy loadingApp + Pages
next/scriptThird-party script loadingApp + Pages
next/fontGoogle and local font optimizationApp + Pages

​
How It Works

vinext’s Vite plugin intercepts next/* imports and resolves them to shim implementations: 
// Your import
import Link from 'next/link'
import { cookies } from 'next/headers'

// Resolved by vinext plugin to:
import Link from 'vinext/shims/link'
import { cookies } from 'vinext/shims/headers'
The shims provide API-compatible implementations that work with:
  • Vite’s module system (ESM, HMR, multi-environment builds)
  • Standard Web APIs (Request, Response, Headers)
  • Multiple runtimes (Node.js, Cloudflare Workers, Deno)

​
Compatibility Notes

​
Full Compatibility

Most Next.js APIs work identically:
  • All navigation APIs (useRouter, usePathname, Link)
  • Server Components APIs (headers, cookies, notFound)
  • Middleware (NextRequest, NextResponse)
  • Image optimization and lazy loading
  • Font optimization (Google Fonts and local)

​
Runtime Differences

vinext uses AsyncLocalStorage for request context isolation. This works in:
  • Node.js 16+ (native)
  • Cloudflare Workers (via polyfill)
  • Deno (native)
In environments without ALS support, a fallback to module-level state is used (not concurrency-safe).
Local image optimization routes through /_vinext/image:
  • Dev mode: Serves original files
  • Cloudflare Workers: Uses Cloudflare Images binding
  • Custom backends: Implement your own handler
Remote images use @unpic/react for CDN-native transforms.
Google Fonts:
  • Dev: Loads from Google Fonts CDN
  • Production: Self-hosted via build-time fetch (no runtime requests)
Local fonts are bundled as assets and served with proper caching headers.

​
Extension Points

​
Custom Cache Handler

Swap the cache backend for Redis, DynamoDB, etc: 
import { setCacheHandler } from 'next/cache'
import { MyCacheHandler } from './cache'

setCacheHandler(new MyCacheHandler())

​
Image Optimization Handler

Intercept /_vinext/image requests in your server: 
if (pathname === '/_vinext/image') {
  const url = searchParams.get('url')
  const width = Number(searchParams.get('w'))
  return optimizeImage(url, width)
}

​
Middleware Context

Access platform-specific context in middleware: 
export function middleware(request: NextRequest) {
  // Cloudflare Workers
  const cf = request.cf
  
  // Custom context
  const ctx = (request as any).__vinext_context
  
  return NextResponse.next()
}

​
Type Safety

All shims are fully typed with TypeScript: 
import type { Metadata } from 'next'
import type { NextRequest, NextResponse } from 'next/server'
import type { ReadonlyURLSearchParams } from 'next/navigation'
Types are compatible with @types/react and the Next.js type definitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us