cloudflare/vinext

vinext

Run Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.

Read the announcement: How we rebuilt Next.js with AI in one week

Under active development. vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.

vinext reimplements the Next.js API surface on Vite rather than consuming next build output. It supports both the App Router and Pages Router, React Server Components, Server Actions, middleware, route handlers, ISR, static export, and the most commonly used next/* modules. Cloudflare Workers has the deepest integration; Node.js and other platforms are available with different levels of support.

Project status

What works today

• App Router and Pages Router in development and production builds
• React Server Components, Server Actions, route handlers, and middleware
• Static generation, ISR, output: "export", and standalone Node.js output
• Core Next.js APIs and modules, including next/link, next/image, next/navigation, next/headers, next/cache, and the Metadata API
• Cloudflare Workers deployment with bindings, cache adapters, and image optimization support
• Migration tooling through vinext check, vinext init, and the vinext Agent Skill

Known gaps we're working on

These are active compatibility areas, not permanent exclusions:

• Cache Components and Partial Prerendering: "use cache" is partially implemented, but full cacheComponents behavior is still incomplete. Cache profiles, tags, partial shells, resume behavior, prefetching, and some dev/build cache semantics do not yet match Next.js in every case.
• Build-time image and font optimization: images can be optimized at request time on Cloudflare, but vinext does not yet reproduce Next.js's complete build-time image pipeline. Google Fonts are loaded from the CDN, and local font CSS is injected at runtime rather than extracted during the build.
• Native modules in App Router development: packages such as sharp, resvg, satori, lightningcss, and @napi-rs/canvas can fail in Vite's RSC development environment. Production builds support more of these cases than development mode.
• Platform-specific and advanced Next.js behavior: runtime and preferredRegion route config are currently ignored, and some recently introduced or undocumented Next.js behavior may not yet be reproduced.

Run vinext check against an existing application before migrating. If a gap is not listed here, check the open issues or file a focused reproduction.

Quick start

Use the official setup commands below. They are the recommended way to create or migrate a vinext project because they configure dependencies, scripts, Vite, and your deployment target for you.

Start a new project with create-vinext-app:

pnpm create vinext-app@latest my-app

Migrate an existing Next.js project with vinext init:

npx vinext init

Optional: migrate with an AI agent

Prefer vinext init for a direct, repeatable migration. If you want an AI agent to investigate compatibility issues and guide the migration, vinext also includes an optional Agent Skill. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools:

npx skills add cloudflare/vinext

Then open your Next.js project in any supported tool and say:

migrate this project to vinext

The skill handles compatibility checking, dependency installation, config generation, and dev server startup. It knows what vinext supports and will flag anything that needs manual attention.

Or do it manually

npm install vinext
npm install -D vite @vitejs/plugin-react

If you're using the App Router, also install:

npm install react-server-dom-webpack
npm install -D @vitejs/plugin-rsc

Replace next with vinext in your scripts:

{
  "scripts": {
    "dev": "vinext dev",
    "build": "vinext build",
    "start": "vinext start"
  }
}

vinext dev          # Development server with HMR
vinext build        # Production build
npx @vinext/cloudflare deploy  # Build and deploy to Cloudflare Workers

With Vite+, use vpx @vinext/cloudflare deploy, or vp exec vinext-cloudflare deploy when running the locally installed bin.

vinext auto-detects your app/ or pages/ directory, loads next.config.js, and configures Vite automatically. No vite.config.ts required for basic usage.

Your existing pages/, app/, next.config.js, and public/ directories work as-is. Run vinext check first to scan for known compatibility issues, or use vinext init to automate the full migration.

CLI reference

Options: -p / --port <port>, -H / --hostname <host>, --turbopack (accepted, no-op).

@vinext/cloudflare deploy options: --preview, --env <name>, --name <name>, --skip-build, --dry-run, --experimental-tpr.

vinext init prompts for a deployment target, defaulting to Cloudflare. Agents must ask the user which target they want, then pass --platform=cloudflare or --platform=node.

Other options: --port <port> (default: 3001), --skip-check, --force.

If your next.config.* sets output: "standalone", vinext build emits a self-hosting bundle at dist/standalone/. Start it with:

node dist/standalone/server.js

Environment variables: PORT (default 3000), HOST (default 0.0.0.0).

Note: Next.js standalone uses HOSTNAME for the bind address, but vinext uses HOST to avoid collision with the system-set HOSTNAME variable on Linux. Update your deployment config accordingly.

Starting a new vinext project

Use create-vinext-app for new projects. It creates a TypeScript App Router project with Tailwind CSS and then runs the same vinext init setup used for existing apps:

pnpm create vinext-app@latest my-app

The generated project is Cloudflare Workers-ready by default. Pass --platform=node if you want the Node target instead.

Migrating an existing Next.js project

vinext init automates the migration in one command:

npx vinext init

This will:

1. Run vinext check to scan for compatibility issues
2. Install vinext runtime packages as dependencies and Vite/plugin tooling as devDependencies
3. Rename CJS config files (e.g. postcss.config.js -> .cjs) to avoid ESM conflicts
4. Add "type": "module" to package.json
5. Add dev:vinext, build:vinext, and start:vinext scripts to package.json
6. Prompt for a deployment platform (Cloudflare by default, or Node)
7. Generate the matching vite.config.ts
8. For Cloudflare, generate wrangler.jsonc

The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify next.config, tsconfig.json, or any source files, and it does not remove Next.js dependencies.

vinext targets Vite 8, which defaults to Rolldown, Oxc, Lightning CSS, and a newer browser baseline. If you bring custom Vite config or plugins from an older setup, prefer oxc, optimizeDeps.rolldownOptions, and build.rolldownOptions over older esbuild and build.rollupOptions knobs, and override build.target if you still need older browsers. If a dependency breaks because of stricter CommonJS default import handling, fix the import or use legacy.inconsistentCjsInterop: true as a temporary escape hatch. See the Vite 8 migration guide.

npm run dev:vinext    # Start the vinext dev server (port 3001)
npm run build:vinext  # Build production output with vinext
npm run start:vinext  # Start vinext production server
npm run dev           # Still runs Next.js as before

Use --platform=cloudflare or --platform=node to skip the platform prompt. Cloudflare init updates an existing JavaScript or TypeScript Vite config using its AST, preserving unrelated settings. Use --force to replace an existing Node-target Vite config, or --skip-check to skip the compatibility report.

Why

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 reimplements the Next.js API surface on Vite so existing Next.js applications can run on a different toolchain. The answer, so far, is that substantial applications can.

vinext works everywhere. It natively supports Cloudflare Workers (with npx @vinext/cloudflare deploy or vp exec vinext-cloudflare deploy, bindings, KV caching), and can be deployed to Vercel, Netlify, AWS, Deno Deploy, and more via the Nitro Vite plugin. Native support for additional platforms is planned.

Alternatives worth knowing about:

• OpenNext — adapts next build output for AWS, Cloudflare, and other platforms. OpenNext has been around much longer than vinext, is more mature, and covers more of the Next.js API surface because it builds on top of Next.js's own output rather than reimplementing it. If you want the safer, more proven option, start there.
• Next.js self-hosting — Next.js can be deployed to any Node.js server, Docker container, or as a static export.

Design principles

• Deploy anywhere. Natively supports Cloudflare Workers, with other platforms available via Nitro. Native adapters for more platforms are planned.
• 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.

FAQ

What is this? 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. It can be deployed anywhere: Cloudflare Workers is the first natively supported target, with other platforms available via Nitro. Native adapters for more platforms are planned.

Is this a fork of Next.js? No. vinext is an alternative implementation of the Next.js API surface built on Vite. The core is written from scratch. The goal is not to create a competing framework or add features beyond what Next.js offers; it is to provide the same well-defined API surface on Vite's toolchain.

Does vinext require Next.js to be installed? No. vinext ships fallback declarations for the supported next and next/* APIs, so applications can run and type-check without the next package. If both packages are installed, vinext keeps using Next.js's authoritative types and adds only its own extensions. Compatibility features that consume Next.js internals, such as styled-jsx, may still require a matching Next.js installation when used.

How is this different from OpenNext? OpenNext adapts the output of a standard next build to run on various platforms. Because it builds on Next.js's own output, it inherits broad API coverage and has been well-tested for much longer. vinext takes a different approach: it reimplements the Next.js APIs on Vite from scratch, which means faster builds and smaller bundles, but less coverage of the long tail of Next.js features. If you need a mature, well-tested way to run Next.js outside Vercel, OpenNext is the safer choice. If you want a lighter Vite-based toolchain and do not need every Next.js API, vinext may be a good fit.

Can I use this in production? You can, with caution. vinext has known compatibility gaps and has not yet been battle-tested across the full range of production Next.js workloads. Evaluate the features and deployment target your application relies on before adopting it.

Can I just self-host Next.js? Yes. Next.js supports self-hosting on Node.js servers, Docker containers, and static exports. If you're happy with the Next.js toolchain and just want to run it somewhere other than Vercel, self-hosting is the simplest path.

How are you verifying this works? The test suite has over 1,700 Vitest tests and 380 Playwright E2E tests. This includes tests ported directly from the Next.js test suite and OpenNext's Cloudflare conformance suite, covering routing, SSR, RSC, server actions, caching, metadata, middleware, streaming, and more. Vercel's App Router Playground also runs on vinext as an integration test. See the Tests section and tests/nextjs-compat/TRACKING.md for details.

Who is reviewing this code? A mix of humans and AI agents. Humans review PRs before they merge, focused on behavior, structure, and long-term direction. We lean heavily on agent-driven code review to catch issues at PR time and across the codebase. The test suite is the primary quality gate. Outside contributions and deeper human code review are very welcome.

Why Vite? Vite is an excellent build tool with a rich plugin ecosystem, first-class ESM support, and fast HMR. The @vitejs/plugin-rsc plugin adds React Server Components support with multi-environment builds. vinext builds the Next.js developer experience on top of that infrastructure.

Does this support the Pages Router, App Router, or both? Both. File-system routing, SSR, client hydration, and deployment to Cloudflare Workers work for both routers.

What version of Next.js does this target? Next.js 16.x. No support for deprecated APIs from older versions.

Can I deploy to AWS/Netlify/other platforms? Yes. Add the Nitro Vite plugin alongside vinext, and you can deploy to Vercel, Netlify, AWS Amplify, Deno Deploy, Azure, and many more. See Other platforms (via Nitro) for setup. For Cloudflare Workers, the native integration (npx @vinext/cloudflare deploy or vp exec vinext-cloudflare deploy) gives you the smoothest experience. Native adapters for more platforms are planned.

What happens when Next.js releases a new feature? We track the public Next.js API surface and add support for new stable features. Experimental or unstable Next.js features are lower priority. The plan is to add commit-level tracking of the Next.js repo so we can stay current as new versions are released.

Deployment

Cloudflare Workers

vinext has native integration with Cloudflare Workers through @cloudflare/vite-plugin, including bindings access via cloudflare:workers, KV caching, image optimization, and the @vinext/cloudflare deploy one-command workflow.

Prerequisites

Before running npx @vinext/cloudflare deploy for the first time you need to authenticate with Cloudflare and tell wrangler which account to deploy to.

Authentication — pick one:

• wrangler login (recommended for local development) — opens a browser window to authenticate. Run it once and wrangler caches the token.
• CLOUDFLARE_API_TOKEN env var (CI / non-interactive) — create a token at dash.cloudflare.com/profile/api-tokens using the Edit Cloudflare Workers template. That template grants all the permissions @vinext/cloudflare deploy needs.

Account ID:

wrangler needs to know which Cloudflare account to deploy to. Add your account ID to wrangler.jsonc:

{
  "account_id": "<your-account-id>",
  ...
}

Find your account ID in the Cloudflare dashboard URL (dash.cloudflare.com/<account-id>) or by running wrangler whoami after logging in.

Alternatively, set the CLOUDFLARE_ACCOUNT_ID environment variable instead of hardcoding it in the config file.

Run vinext init --platform=cloudflare first to install dependencies and create or AST-update vite.config.* and wrangler.jsonc. @vinext/cloudflare deploy then validates that setup, builds the application, and deploys to Workers without rewriting project configuration.

Cloudflare init can also configure image optimization declaratively in the Vite config with imagesOptimizer() and add the matching Wrangler Images binding. The built-in fetch handlers register that optimizer at runtime; image optimization is not implemented or generated by @vinext/cloudflare deploy.

npx @vinext/cloudflare deploy
vp exec vinext-cloudflare deploy
npx @vinext/cloudflare deploy --env staging
vp exec vinext-cloudflare deploy --env staging

Use --env <name> to target wrangler.jsonc env.<name>. --preview is shorthand for --env preview.

The init command also auto-detects and fixes common migration issues:

• Adds "type": "module" to package.json if missing
• Resolves tsconfig.json path aliases automatically with Vite's native resolver
• Detects MDX usage and configures @mdx-js/rollup
• Renames CJS config files (postcss.config.js, etc.) to .cjs when needed
• Detects native Node.js modules (sharp, resvg, satori, lightningcss, @napi-rs/canvas) and auto-stubs them for Workers. If you encounter others that need stubbing, PRs are welcome.

Both App Router and Pages Router work on Workers with full client-side hydration.

Cloudflare Bindings (D1, R2, KV, AI, etc.)

Use import { env } from "cloudflare:workers" to access bindings in any server component, route handler, or server action. No custom worker entry or special configuration required.

import { env } from "cloudflare:workers";

export default async function Page() {
  const result = await env.DB.prepare("SELECT * FROM posts").all();
  return <div>{JSON.stringify(result)}</div>;
}

This works because @cloudflare/vite-plugin runs the RSC environment in workerd, where cloudflare:workers is a native module. In production builds, the import is externalized so workerd resolves it at runtime. All binding types are supported: D1, R2, KV, Durable Objects, AI, Queues, Vectorize, Browser Rendering, etc.

Define your bindings in wrangler.jsonc as usual:

{
  "name": "my-app",
  "compatibility_date": "2026-02-12",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "..." }],
  "kv_namespaces": [{ "binding": "CACHE", "id": "..." }],
}

For TypeScript types, generate them with wrangler types and the env import will be fully typed.

Note: You do not need getPlatformProxy(), a custom worker entry with fetch(request, env), or any other workaround. cloudflare:workers is the recommended way to access bindings in vinext.

Traffic-aware Pre-Rendering (experimental)

TPR queries Cloudflare zone analytics at deploy time to find which pages actually get traffic, pre-renders only those, and uploads them to KV cache. The result is SSG-level latency for popular pages without pre-rendering your entire site.

npx @vinext/cloudflare deploy --experimental-tpr                    # Pre-render pages covering 90% of traffic
vp exec vinext-cloudflare deploy --experimental-tpr                 # Same, with Vite+
npx @vinext/cloudflare deploy --experimental-tpr --tpr-coverage 95  # More aggressive coverage
npx @vinext/cloudflare deploy --experimental-tpr --tpr-limit 500    # Cap at 500 pages
npx @vinext/cloudflare deploy --experimental-tpr --tpr-window 48    # Use 48h of analytics

Requires a custom domain (zone analytics are unavailable on *.workers.dev) and CLOUDFLARE_API_TOKEN with Zone.Analytics read permission.

Custom Vite configuration

If you need to customize the Vite config, create a vite.config.ts. vinext will merge its config with yours. For Cloudflare Workers deployment with the App Router, configure @cloudflare/vite-plugin so the RSC environment runs in workerd:

import { defineConfig } from "vite";
import vinext from "vinext";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [
    vinext(),
    cloudflare({
      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
    }),
  ],
});

Do not register @vitejs/plugin-rsc yourself. It is an optional peer dependency, so it must be installed in your project, but vinext auto-registers it whenever an app/ directory is detected. Adding an explicit rsc() call fails the build with [vinext] Duplicate @vitejs/plugin-rsc detected. Pass rsc: false to vinext() only if you want to own that registration.

See the examples for complete working configurations.

Other platforms (via Nitro)

For deploying to platforms other than Cloudflare, vinext works with Nitro as a Vite plugin. Add nitro alongside vinext in your Vite config and deploy to any Nitro-supported platform.

import { defineConfig } from "vite";
import vinext from "vinext";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [vinext(), nitro()],
});

npm install nitro

Nitro auto-detects the deployment platform in most CI/CD environments (Vercel, Netlify, AWS Amplify, Azure, and others), so you typically don't need to set a preset. For local builds, set the NITRO_PRESET environment variable:

NITRO_PRESET=vercel npx vite build
NITRO_PRESET=netlify npx vite build
NITRO_PRESET=deno_deploy npx vite build

Deploying to Cloudflare? You can use Nitro, but the native integration (npx @vinext/cloudflare deploy, vp exec vinext-cloudflare deploy, and @cloudflare/vite-plugin) is recommended. It provides the best developer experience with cloudflare:workers bindings, KV caching, image optimization, and one-command deploys.

NITRO_PRESET=vercel npx vite build

NITRO_PRESET=netlify npx vite build

NITRO_PRESET=aws_amplify npx vite build

NITRO_PRESET=deno_deploy npx vite build
cd .output
deployctl deploy --project=my-project server/index.ts

NITRO_PRESET=node npx vite build
node .output/server/index.mjs

See the Nitro deployment docs for the full list of supported platforms and provider-specific configuration.

Live examples

These are deployed to Cloudflare Workers and updated on every push to main:

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

Every next/* import is shimmed to a Vite-compatible implementation.

Routing

Server features

Configuration

Environment variable loading (.env*)

vinext automatically loads dotenv files for dev, build, start, and deploy.

Load order matches Next.js (highest priority first):

1. Existing process.env values (shell/CI)
2. .env.<mode>.local
3. .env.local (skipped when mode is test)
4. .env.<mode>
5. .env

Modes:

• vinext dev uses development
• vinext build, vinext start, and @vinext/cloudflare deploy use production

Variable expansion ($VAR / ${VAR}) is supported.

Client exposure remains explicit:

• NEXT_PUBLIC_* variables are inlined for browser usage
• next.config.js env entries are also inlined
• Other env vars stay server-only unless you explicitly expose them through Vite (for example VITE_* + import.meta.env)

Override behavior:

• To override any .env* value, set it in your shell/CI environment before running vinext. Existing process.env always wins.

Caching

The cache is pluggable. The default MemoryCacheHandler works out of the box. Swap in your own backend for production.

Configuring cache adapters from vite.config

Instead of wiring up cache handlers imperatively from a worker entry, you can declare them in the vinext() plugin config. The @vinext/cloudflare package ships Cloudflare adapters for this:

• kvDataAdapter() (@vinext/cloudflare/cache/kv-data-adapter) — backs the "use cache" data cache with a Workers KV namespace.

import { defineConfig } from "vite";
import vinext from "vinext";
import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";

export default defineConfig({
  plugins: [
    vinext({
      cache: {
        data: kvDataAdapter(),
      },
    }),
  ],
});

The KV data adapter reads env[binding] at runtime, so add the matching KV namespace to your wrangler.jsonc:

{
  "kv_namespaces": [{ "binding": "VINEXT_KV_CACHE", "id": "<your-namespace-id>" }],
}

binding defaults to VINEXT_KV_CACHE, so kvDataAdapter() with no options works as long as that's your binding name. Other options: appPrefix (namespace cache keys to isolate multiple apps in one KV namespace), ttlSeconds (default KV expirationTtl, default 30 days), and tagCacheTtlMs (in-memory tag-invalidation cache TTL, default 5s).

Each builder returns a plain, serializable { adapter, options } descriptor — it never touches the Workers runtime, so nothing throws at build or dev time when bindings aren't available. The actual adapter (and its env binding lookup) is instantiated lazily on the first request.

Registration is wired into every router and runtime — App Router and Pages Router, on Cloudflare Workers as well as the Node.js server (vinext start) and dev. It self-guards (instantiated once per isolate) and is resilient: if an adapter can't initialize on a given runtime (e.g. a KV binding doesn't exist on the Node server), vinext logs a warning and falls back to the default handler instead of failing requests.

To write your own adapter, point a slot at any module by path and default-export a factory that receives { env, options } at runtime and returns a data-cache CacheHandler (or a CDN adapter):

vinext({
  cache: {
    data: {
      adapter: require.resolve("./my-adapter.js"),
      options: {/* … */},
    },
  },
});

What's NOT supported (and won't be)

These are intentional exclusions. For things that are missing today but on the roadmap, see Known gaps we're working on above.

• Vercel-specific features — @vercel/og edge runtime, Vercel Analytics integration, Vercel KV/Blob/Postgres bindings. Use platform equivalents.
• AMP — Deprecated since Next.js 13. useAmp() returns false.
• next export (legacy) — Use output: 'export' in config instead.
• Turbopack/webpack configuration — This runs on Vite. Use Vite plugins instead of webpack loaders/plugins.
• next/jest — Use Vitest.
• create-next-app scaffolding — Use create-vinext-app for new vinext projects.
• Bug-for-bug parity with undocumented behavior — If it's not in the Next.js docs, we probably don't replicate it.

Benchmarks

Caveat: Benchmarks are hard to get right and these are early results. Take them as directional, not definitive.

These benchmarks measure compilation and bundling speed, not production serving performance. Next.js and vinext have fundamentally different default approaches: Next.js statically pre-renders pages at build time (making builds slower but production serving faster for static content), while vinext server-renders all pages on each request. To make the comparison apples-to-apples, the benchmark app uses export const dynamic = "force-dynamic" to disable Next.js static pre-rendering — both frameworks are doing the same work: compiling, bundling, and preparing server-rendered routes.

The benchmark app is a shared 33-route App Router application (server components, client components, dynamic routes, nested layouts, API routes) built identically by both tools. We compare Next.js (Turbopack) against vinext (Vite 8). Both Turbopack and Rolldown parallelize across cores, so results on machines with more cores may differ significantly.

We measure three things:

• Production build time — 5 runs, timed with hyperfine.
• Client bundle size — gzipped output of each build.
• Dev server cold start — 10 runs, randomized execution order. Vite's dependency optimizer cache is cleared before each run.

Benchmarks run on GitHub CI runners (2-core Ubuntu) on every merge to main. See the launch numbers in the announcement blog post and the latest results at vinext-web.vinext.workers.dev/benchmarks.

Reproduce with node benchmarks/run.mjs --runs=5 --dev-runs=10. Exact framework versions are recorded in each result.

Architecture

vinext is a Vite plugin that:

1. Resolves all next/* imports to local shim modules that reimplement the Next.js API using standard Web APIs and React primitives.
2. Scans your pages/ and app/ directories to build a file-system router matching Next.js conventions.
3. Generates virtual entry modules for the RSC, SSR, and browser environments that handle request routing, component rendering, and client hydration.
4. Integrates with @vitejs/plugin-rsc for React Server Components — handling "use client" / "use server" directives, RSC stream serialization, and multi-environment builds.

The result is a standard Vite application that happens to be API-compatible with Next.js.

Pages Router flow

Request → Vite dev server middleware → Route match → getServerSideProps/getStaticProps
  → renderToReadableStream(App + Page) → HTML with __NEXT_DATA__ → Client hydration

App Router flow

Request → RSC entry (Vite rsc environment) → Route match → Build layout/page tree
  → renderToReadableStream (RSC payload) → SSR entry (Vite ssr environment)
  → renderToReadableStream (HTML) → Client hydration from RSC stream

Project structure

packages/vinext/
  src/
    index.ts              # Main plugin — resolve aliases, config, virtual modules
    cli.ts                # vinext CLI (dev/build/start/deploy/init/check/lint)
    check.ts              # Compatibility scanner
    deploy.ts             # Cloudflare Workers deployment
    init.ts               # vinext init — one-command migration for Next.js apps
    client/
      entry.ts            # Client-side hydration entry
    routing/
      pages-router.ts     # Pages Router file-system scanner
      app-router.ts       # App Router file-system scanner
    entries/
      app-rsc-entry.ts    # App Router RSC entry generator
      app-ssr-entry.ts    # App Router SSR entry generator
      app-browser-entry.ts # App Router browser entry generator
      pages-server-entry.ts # Pages Router SSR entry generator
      pages-client-entry.ts # Pages Router client entry generator
    server/
      dev-server.ts       # Pages Router SSR request handler
      prod-server.ts      # Production server with compression
      api-handler.ts      # Pages Router API routes
      isr-cache.ts        # ISR cache layer
      middleware.ts        # middleware.ts / proxy.ts runner
      metadata-routes.ts  # File-based metadata route scanner
      instrumentation.ts  # instrumentation.ts support
    shims/                # One file per next/* module (33 shims + 6 internal)
    build/
      static-export.ts    # output: 'export' support
    utils/
      project.ts          # Shared project utilities (ESM, CJS, package manager detection)
    config/
      next-config.ts      # next.config.js loader
      config-matchers.ts  # Config matching utilities

tests/
  *.test.ts               # Vitest unit + integration tests
  nextjs-compat/          # Tests ported from Next.js test suite
  fixtures/               # Test apps (pages-basic, app-basic, ecosystem libs)
  e2e/                    # Playwright E2E tests (5 projects)

examples/                 # Deployed demo apps (see Live Examples above)

Tests

pnpm test             # Vitest unit + integration tests
pnpm run test:e2e     # Playwright E2E tests (5 projects)
pnpm run check        # Format, lint, and type checks
pnpm run lint         # Lint only (type-aware oxlint)
pnpm run fmt          # Formatting (oxfmt)
pnpm run fmt:check    # Check formatting without writing

E2E tests cover Pages Router (dev + production), App Router (dev), and both routers on Cloudflare Workers via wrangler dev.

The Vercel App Router Playground runs on vinext as an integration test — see it live at app-router-playground.vinext.workers.dev.

Local setup (from source)

If you're working from the repo instead of installing from npm:

git clone https://github.com/cloudflare/vinext.git
cd vinext
pnpm install
pnpm run build

This builds the vinext package to packages/vinext/dist/. For active development, use pnpm --filter vinext run dev to rebuild on changes.

To use it against an external Next.js app, link the built package:

# From your Next.js project directory:
pnpm link /path/to/vinext/packages/vinext

Or add it to your package.json as a file dependency:

{
  "dependencies": {
    "vinext": "file:/path/to/vinext/packages/vinext"
  }
}

vinext has peer dependencies on react ^19.2.6, react-dom ^19.2.6, react-server-dom-webpack ^19.2.6, and vite ^8.0.0. Then replace next with vinext in your scripts and run as normal.

Contributing

This project is under active development. Issues and PRs are welcome.

CI

When you open a PR, CI (check, Vitest, Playwright E2E) runs automatically. First-time contributors need one manual approval from a maintainer, then subsequent PRs run without intervention.

Deploy previews (building and deploying examples to Cloudflare Workers) only run for branches pushed to the main repo. If you're a Cloudflare employee, push your branch to the main repo instead of forking, and previews deploy automatically. For fork PRs, a maintainer can comment /deploy-preview to trigger the deploy and post preview URLs.

Reporting bugs

If something doesn't work with your Next.js app, please file an issue — we want to hear about it.

Before you do, try pointing an AI agent at the problem. Open your project with Claude Code, Cursor, OpenCode, or whatever you use, and ask it to figure out why your app isn't working with vinext. In our experience, agents are very good at tracing through the vinext source, identifying the gap or bug, and often producing a fix or at least a clear diagnosis. An issue that includes "here's what the agent found" is significantly more actionable than "it doesn't work."

Even a partial diagnosis helps — stack traces, which next/* import is involved, whether it's a dev or production build issue, App Router vs Pages Router. The more context, the faster we can fix it.

License

MIT