Known Limitations

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.

​

Current Limitations

​

Image Optimization

• Remote images: Work via @unpic/react, which auto-detects 28 CDN providers including Cloudinary, Imgix, and Cloudflare Images
• Local images: Routed through a /_vinext/image endpoint that can resize and transcode on Cloudflare Workers (via the Images binding) in production
• Missing: Build-time optimization, static image resizing, automatic format conversion during build

import Image from "next/image";

// Remote images work with CDN optimization
<Image
  src="https://example.com/photo.jpg"
  width={800}
  height={600}
  alt="Photo"
/>

// Local images work but without build-time optimization
import photo from "./photo.jpg";
<Image src={photo} alt="Photo" />

​

Font Loading

• Fonts are loaded at runtime via CDN links
• No size-adjust fallback font metrics
• No build-time subsetting or optimization
• Local fonts work but @font-face CSS is injected at runtime, not extracted at build time

import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });
// Loads from Google Fonts CDN at runtime

​

Layout Segment Hooks

• Works correctly for most use cases
• May differ from Next.js in edge cases with parallel routes
• The hook infers segments from URL structure instead of React component tree position

​

Route Segment Config

// Parsed but ignored
export const runtime = "edge";
export const preferredRegion = "iad1";

// These work correctly
export const revalidate = 60;
export const dynamic = "force-static";
export const dynamicParams = true;

​

Node.js Production Server

• Cloudflare Workers is the primary deployment target
• The Node.js server is intended for local testing only
• Some features may behave differently on Node.js vs Workers
• For production, use vinext deploy to deploy to Cloudflare Workers

​

Native Node Modules in Dev Mode

• Dynamic OG image/icon routes using these modules work in production builds
• They don’t work in dev mode due to Vite’s RSC environment limitations
• These are auto-stubbed during vinext deploy
• Workaround: Test OG images in production build (vinext build && vinext start)

​

Intentionally Not Supported

​

Vercel-Specific Features

• @vercel/og edge runtime — Use the standard version instead
• Vercel Analytics integration — Use Cloudflare Analytics or Web Analytics
• Vercel KV/Blob/Postgres bindings — Use Cloudflare equivalents (Workers KV, R2, D1)

// ❌ Don't use Vercel-specific imports
import { kv } from "@vercel/kv";

// ✅ Use Cloudflare bindings instead
export default async function handler(request, env) {
  const value = await env.MY_KV.get("key");
  return Response.json({ value });
}

​

Deprecated Features

• AMP — Deprecated since Next.js 13. useAmp() returns false
• next export (legacy) — Use output: 'export' in config instead
• Old image component — Use the modern next/image API

​

Build Tool Configuration

• Turbopack/webpack configuration — vinext runs on Vite. Use Vite plugins instead
• webpack loaders — Use equivalent Vite plugins
• Turbopack config — Use Vite config instead

// ❌ webpack config doesn't apply
module.exports = {
  webpack: (config) => {
    // This won't work
    return config;
  },
};

// ✅ Use Vite config instead
import { defineConfig } from "vite";
import vinext from "vinext";

export default defineConfig({
  plugins: [
    vinext(),
    // Add Vite plugins here
  ],
});

​

Testing

• next/jest — Use Vitest instead, which has better Vite integration

# ❌ Don't use next/jest
npm install --save-dev jest @testing-library/react @testing-library/jest-dom

# ✅ Use Vitest
npm install --save-dev vitest @testing-library/react @testing-library/dom

​

Scaffolding

• create-next-app scaffolding — Not a goal. Use manual installation or migrate an existing Next.js app

​

Bug-for-Bug Parity

​

RSC Module Caching (Dev Mode)

// May return cached value in dev mode
const timestamp = Date.now();

​

Workarounds

​

Image Optimization

// Use Cloudflare Images with automatic optimization
<Image
  src="https://imagedelivery.net/YOUR_ACCOUNT_HASH/image-id/public"
  width={800}
  height={600}
  alt="Photo"
/>

​

Font Optimization

import { Inter } from "next/font/local";

const inter = Inter({
  src: "./fonts/inter-var.woff2",
  variable: "--font-inter",
});

​

Native Modules in Dev

vinext build
vinext start
# Navigate to /api/og routes

​

Reporting Issues

1. Check the GitHub issues
2. Search the test tracking document
3. File a new issue with:
   • What you’re trying to do
   • The error message or unexpected behavior
   • A minimal reproduction if possible