{ "markdown": "# vinext\n\nRun Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.\n\n**Website:** [vinext.dev](https://vinext.dev)\n\n> **Read the announcement:** [How we rebuilt Next.js with AI in one week](https://blog.cloudflare.com/vinext/)\n\n> **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.\n\nvinext 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.\n\n## Project status\n\n### What works today\n\n- **App Router and Pages Router** in development and production builds\n- **React Server Components, Server Actions, route handlers, and middleware**\n- **Static generation, ISR, `output: \"export\"`, and standalone Node.js output**\n- **Core Next.js APIs and modules**, including `next/link`, `next/image`, `next/navigation`, `next/headers`, `next/cache`, and the Metadata API\n- **Cloudflare Workers deployment** with bindings, cache adapters, and image optimization support\n- **Migration tooling** through `vinext check`, `vinext init`, and the vinext Agent Skill\n\n### Known gaps we're working on\n\nThese are active compatibility areas, not permanent exclusions:\n\n- **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.\n- **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.\n- **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.\n- **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.\n\nRun `vinext check` against an existing application before migrating. If a gap is not listed here, check the [open issues](https://github.com/cloudflare/vinext/issues) or file a focused reproduction.\n\n## Quick start\n\n**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.\n\nStart a new project with `create-vinext-app`:\n\n```bash\npnpm create vinext-app@latest my-app\n```\n\nMigrate an existing Next.js project with `vinext init`:\n\n```bash\nnpx vinext init\n```\n\n### Optional: migrate with an AI agent\n\nPrefer `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](https://agentskills.io/home). It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools:\n\n```sh\nnpx skills add cloudflare/vinext\n```\n\nThen open your Next.js project in any supported tool and say:\n\n```\nmigrate this project to vinext\n```\n\nThe 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.\n\n### Or do it manually\n\n```bash\nnpm install vinext\nnpm install -D vite @vitejs/plugin-react\n```\n\nIf you're using the App Router, also install:\n\n```bash\nnpm install react-server-dom-webpack\nnpm install -D @vitejs/plugin-rsc\n```\n\nReplace `next` with `vinext` in your scripts:\n\n```json\n{\n \"scripts\": {\n \"dev\": \"vinext dev\",\n \"build\": \"vinext build\",\n \"start\": \"vinext start\"\n }\n}\n```\n\n```bash\nvinext dev # Development server with HMR\nvinext build # Production build\nnpx @vinext/cloudflare deploy # Build and deploy to Cloudflare Workers\n```\n\nWith Vite+, use `vpx @vinext/cloudflare deploy`, or\n`vp exec vinext-cloudflare deploy` when running the locally installed bin.\n\nvinext auto-detects your `app/` or `pages/` directory, loads `next.config.js`, and configures Vite automatically. No `vite.config.ts` required for basic usage.\n\nYour 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](#migrating-an-existing-nextjs-project).\n\n### CLI reference\n\n| Command | Description |\n| ---------------------------------- | ----------------------------------------------------------------------- |\n| `vinext dev` | Start dev server with HMR |\n| `vinext build` | Production build (multi-environment for App Router: RSC + SSR + client) |\n| `vinext start` | Start local production server for testing |\n| `npx @vinext/cloudflare deploy` | Build and deploy to Cloudflare Workers |\n| `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+ |\n| `vinext init` | Migrate a Next.js project to run under vinext |\n| `vinext check` | Scan your Next.js app for compatibility issues before migrating |\n| `vinext lint` | Delegate to eslint or oxlint |\n\nOptions: `-p / --port `, `-H / --hostname `, `--turbopack` (accepted, no-op).\n\n`@vinext/cloudflare deploy` options: `--preview`, `--env `, `--name `, `--skip-build`, `--dry-run`, `--experimental-tpr`.\n\n`vinext init` prompts for a deployment target, defaulting to Cloudflare. Agents must ask the\nuser which target they want, then pass `--platform=cloudflare` or `--platform=node`.\n\nOther options: `--port ` (default: 3001), `--skip-check`, `--force`.\n\nIf your `next.config.*` sets `output: \"standalone\"`, `vinext build` emits a self-hosting bundle at `dist/standalone/`. Start it with:\n\n```bash\nnode dist/standalone/server.js\n```\n\nEnvironment variables: `PORT` (default `3000`), `HOST` (default `0.0.0.0`).\n\n> **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.\n\n### Starting a new vinext project\n\nUse `create-vinext-app` for new projects. It creates a TypeScript App Router project\nwith Tailwind CSS and then runs the same vinext init setup used for existing apps:\n\n```bash\npnpm create vinext-app@latest my-app\n```\n\nThe generated project is Cloudflare Workers-ready by default. Pass\n`--platform=node` if you want the Node target instead.\n\n### Migrating an existing Next.js project\n\n`vinext init` automates the migration in one command:\n\n```bash\nnpx vinext init\n```\n\nThis will:\n\n1. Run `vinext check` to scan for compatibility issues\n2. Install vinext runtime packages as dependencies and Vite/plugin tooling as devDependencies\n3. Rename CJS config files (e.g. `postcss.config.js` -> `.cjs`) to avoid ESM conflicts\n4. Add `\"type\": \"module\"` to `package.json`\n5. Add `dev:vinext`, `build:vinext`, and `start:vinext` scripts to `package.json`\n6. Prompt for a deployment platform (Cloudflare by default, or Node)\n7. Generate the matching `vite.config.ts`\n8. For Cloudflare, generate `wrangler.jsonc`\n\nThe 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.\n\nvinext 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](https://vite.dev/guide/migration).\n\n```bash\nnpm run dev:vinext # Start the vinext dev server (port 3001)\nnpm run build:vinext # Build production output with vinext\nnpm run start:vinext # Start vinext production server\nnpm run dev # Still runs Next.js as before\n```\n\nUse `--platform=cloudflare` or `--platform=node` to skip the platform prompt. Cloudflare init\nupdates an existing JavaScript or TypeScript Vite config using its AST, preserving unrelated\nsettings. Use `--force` to replace an existing Node-target Vite config, or `--skip-check` to skip\nthe compatibility report.\n\n## Why\n\nVite 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`](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc) adding React Server Components support, it's now possible to build a full RSC framework on Vite.\n\nvinext 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.\n\nvinext 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](https://v3.nitro.build/) Vite plugin. Native support for additional platforms is [planned](https://github.com/cloudflare/vinext/issues/80).\n\n**Alternatives worth knowing about:**\n\n- **[OpenNext](https://opennext.js.org/)** — 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.\n- **[Next.js self-hosting](https://nextjs.org/docs/app/building-your-application/deploying#self-hosting)** — Next.js can be deployed to any Node.js server, Docker container, or as a static export.\n\n### Design principles\n\n- **Deploy anywhere.** Natively supports Cloudflare Workers, with other platforms available via Nitro. Native adapters for more platforms are [planned](https://github.com/cloudflare/vinext/issues/80).\n- **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.\n- **Latest Next.js only.** Targets Next.js 16.x. No support for deprecated APIs from older versions.\n- **Incremental adoption.** Drop in the plugin, fix what breaks, deploy.\n\n## FAQ\n\n**What is this?**\nvinext 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](https://github.com/cloudflare/vinext/issues/80).\n\n**Is this a fork of Next.js?**\nNo. 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.\n\n**Does vinext require Next.js to be installed?**\nNo. 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.\n\n**How is this different from OpenNext?**\n[OpenNext](https://opennext.js.org/) 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.\n\n**Can I use this in production?**\nYou 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.\n\n**Can I just self-host Next.js?**\nYes. Next.js supports [self-hosting](https://nextjs.org/docs/app/building-your-application/deploying#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.\n\n**How are you verifying this works?**\nThe test suite has over 1,700 Vitest tests and 380 Playwright E2E tests. This includes tests ported directly from the [Next.js test suite](https://github.com/vercel/next.js/tree/canary/test) and [OpenNext's Cloudflare conformance suite](https://github.com/opennextjs/opennextjs-cloudflare), covering routing, SSR, RSC, server actions, caching, metadata, middleware, streaming, and more. Vercel's [App Router Playground](https://github.com/vercel/next-app-router-playground) also runs on vinext as an integration test. See the [Tests](#tests) section and `tests/nextjs-compat/TRACKING.md` for details.\n\n**Who is reviewing this code?**\nA 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.\n\n**Why Vite?**\nVite is an excellent build tool with a rich plugin ecosystem, first-class ESM support, and fast HMR. The [`@vitejs/plugin-rsc`](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc) plugin adds React Server Components support with multi-environment builds. vinext builds the Next.js developer experience on top of that infrastructure.\n\n**Does this support the Pages Router, App Router, or both?**\nBoth. File-system routing, SSR, client hydration, and deployment to Cloudflare Workers work for both routers.\n\n**What version of Next.js does this target?**\nNext.js 16.x. No support for deprecated APIs from older versions.\n\n**Can I deploy to AWS/Netlify/other platforms?**\nYes. Add the [Nitro](https://v3.nitro.build/) Vite plugin alongside vinext, and you can deploy to Vercel, Netlify, AWS Amplify, Deno Deploy, Azure, and [many more](https://v3.nitro.build/deploy). See [Other platforms (via Nitro)](#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](https://github.com/cloudflare/vinext/issues/80).\n\n**What happens when Next.js releases a new feature?**\nWe 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.\n\n## Deployment\n\n### Cloudflare Workers\n\nvinext 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.\n\n#### Prerequisites\n\nBefore running `npx @vinext/cloudflare deploy` for the first time you need to authenticate with Cloudflare and tell wrangler which account to deploy to.\n\n**Authentication — pick one:**\n\n- **`wrangler login`** (recommended for local development) — opens a browser window to authenticate. Run it once and wrangler caches the token.\n- **`CLOUDFLARE_API_TOKEN` env var** (CI / non-interactive) — create a token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) using the **Edit Cloudflare Workers** template. That template grants all the permissions `@vinext/cloudflare deploy` needs.\n\n**Account ID:**\n\nwrangler needs to know which Cloudflare account to deploy to. Add your account ID to `wrangler.jsonc`:\n\n```jsonc\n{\n \"account_id\": \"\",\n ...\n}\n```\n\nFind your account ID in the Cloudflare dashboard URL (`dash.cloudflare.com/`) or by running `wrangler whoami` after logging in.\n\nAlternatively, set the `CLOUDFLARE_ACCOUNT_ID` environment variable instead of hardcoding it in the config file.\n\nRun `vinext init --platform=cloudflare` first to install dependencies and create or AST-update\n`vite.config.*` and `wrangler.jsonc`. `@vinext/cloudflare deploy` then validates that setup, builds the\napplication, and deploys to Workers without rewriting project configuration.\n\nCloudflare init can also configure image optimization declaratively in the Vite config with\n`imagesOptimizer()` and add the matching Wrangler Images binding. The built-in fetch handlers register\nthat optimizer at runtime; image optimization is not implemented or generated by `@vinext/cloudflare deploy`.\n\n```bash\nnpx @vinext/cloudflare deploy\nvp exec vinext-cloudflare deploy\nnpx @vinext/cloudflare deploy --env staging\nvp exec vinext-cloudflare deploy --env staging\n```\n\nUse `--env ` to target `wrangler.jsonc` `env.`. `--preview` is shorthand for `--env preview`.\n\nThe init command also auto-detects and fixes common migration issues:\n\n- Adds `\"type\": \"module\"` to package.json if missing\n- Resolves tsconfig.json path aliases automatically with Vite's native resolver\n- Detects MDX usage and configures `@mdx-js/rollup`\n- Renames CJS config files (postcss.config.js, etc.) to `.cjs` when needed\n- 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.\n\nBoth App Router and Pages Router work on Workers with full client-side hydration.\n\n#### Cloudflare Bindings (D1, R2, KV, AI, etc.)\n\nUse `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.\n\n```tsx\nimport { env } from \"cloudflare:workers\";\n\nexport default async function Page() {\n const result = await env.DB.prepare(\"SELECT * FROM posts\").all();\n return
{JSON.stringify(result)}
;\n}\n```\n\nThis 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.\n\nDefine your bindings in `wrangler.jsonc` as usual:\n\n```jsonc\n{\n \"name\": \"my-app\",\n \"compatibility_date\": \"2026-02-12\",\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"my-db\", \"database_id\": \"...\" }],\n \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"...\" }],\n}\n```\n\nFor TypeScript types, generate them with `wrangler types` and the `env` import will be fully typed.\n\n> **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.\n\n#### Traffic-aware Pre-Rendering (experimental)\n\nTPR 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.\n\n```bash\nnpx @vinext/cloudflare deploy --experimental-tpr # Pre-render pages covering 90% of traffic\nvp exec vinext-cloudflare deploy --experimental-tpr # Same, with Vite+\nnpx @vinext/cloudflare deploy --experimental-tpr --tpr-coverage 95 # More aggressive coverage\nnpx @vinext/cloudflare deploy --experimental-tpr --tpr-limit 500 # Cap at 500 pages\nnpx @vinext/cloudflare deploy --experimental-tpr --tpr-window 48 # Use 48h of analytics\n```\n\nRequires a custom domain (zone analytics are unavailable on `*.workers.dev`) and `CLOUDFLARE_API_TOKEN` with Zone.Analytics read permission.\n\n#### Custom Vite configuration\n\nIf 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:\n\n```ts\nimport { defineConfig } from \"vite\";\nimport vinext from \"vinext\";\nimport { cloudflare } from \"@cloudflare/vite-plugin\";\n\nexport default defineConfig({\n plugins: [\n vinext(),\n cloudflare({\n viteEnvironment: { name: \"rsc\", childEnvironments: [\"ssr\"] },\n }),\n ],\n});\n```\n\n> **Do not register `@vitejs/plugin-rsc` yourself.** It is an optional peer dependency, so it must be\n> _installed_ in your project, but vinext auto-registers it whenever an `app/` directory is detected.\n> Adding an explicit `rsc()` call fails the build with `[vinext] Duplicate @vitejs/plugin-rsc detected`.\n> Pass `rsc: false` to `vinext()` only if you want to own that registration.\n\n#### Module Federation (client-side)\n\nFor client-side Module Federation, configure React and React DOM as singleton shared modules in both the host and remotes:\n\n```ts\nimport { federation } from \"@module-federation/vite\";\nimport { defineConfig } from \"vite\";\nimport vinext from \"vinext\";\n\nexport default defineConfig({\n plugins: [\n federation({\n name: \"host\",\n shared: {\n react: { singleton: true },\n \"react/\": { singleton: true },\n \"react-dom\": { singleton: true },\n \"react-dom/\": { singleton: true },\n },\n }),\n vinext(),\n ],\n});\n```\n\nIn a remote client component, use `getVinextReact()` before reading React hooks. vinext registers the host's browser React instance before application modules execute, and the first registration remains stable across remote evaluation and HMR:\n\n```tsx\n\"use client\";\n\nimport * as React from \"react\";\nimport { getVinextReact } from \"vinext/client\";\n\nconst { useState } = getVinextReact(React);\n\nexport function RemoteCounter() {\n const [count, setCount] = useState(0);\n return ;\n}\n```\n\nThis bridge is browser-only. It does not provide App Router Module Federation SSR or transparently replace React imports inside third-party packages; compatible React versions remain the responsibility of the Module Federation `shared` configuration.\n\nSee the [examples](#live-examples) for complete working configurations.\n\n### Other platforms (via Nitro)\n\nFor deploying to platforms other than Cloudflare, vinext works with [Nitro](https://v3.nitro.build/) as a Vite plugin. Add `nitro` alongside `vinext` in your Vite config and deploy to any [Nitro-supported platform](https://v3.nitro.build/deploy).\n\n```ts\nimport { defineConfig } from \"vite\";\nimport vinext from \"vinext\";\nimport { nitro } from \"nitro/vite\";\n\nexport default defineConfig({\n plugins: [vinext(), nitro()],\n});\n```\n\n```bash\nnpm install nitro\n```\n\nNitro 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:\n\n```bash\nNITRO_PRESET=vercel npx vite build\nNITRO_PRESET=netlify npx vite build\nNITRO_PRESET=deno_deploy npx vite build\n```\n\n> **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.\n\n
\nVercel\n\nNitro auto-detects Vercel in CI. For local builds:\n\n```bash\nNITRO_PRESET=vercel npx vite build\n```\n\nDeploy with the [Vercel CLI](https://vercel.com/docs/cli) or connect your Git repo in the Vercel dashboard. Set the build command to `vite build` and the output directory to `.output`.\n\n
\n\n
\nNetlify\n\nNitro auto-detects Netlify in CI. For local builds:\n\n```bash\nNITRO_PRESET=netlify npx vite build\n```\n\nDeploy with the [Netlify CLI](https://docs.netlify.com/cli/get-started/) or connect your Git repo. Set the build command to `vite build`.\n\n
\n\n
\nAWS (Amplify)\n\nNitro auto-detects AWS Amplify in CI. For local builds:\n\n```bash\nNITRO_PRESET=aws_amplify npx vite build\n```\n\nConnect your Git repo in the AWS Amplify console. Set the build command to `vite build`.\n\n
\n\n
\nDeno Deploy\n\n```bash\nNITRO_PRESET=deno_deploy npx vite build\ncd .output\ndeployctl deploy --project=my-project server/index.ts\n```\n\n
\n\n
\nNode.js server\n\n```bash\nNITRO_PRESET=node npx vite build\nnode .output/server/index.mjs\n```\n\nThis produces a standalone Node.js server. Suitable for Docker, VMs, or any environment that can run Node.\n\n
\n\nSee the [Nitro deployment docs](https://v3.nitro.build/deploy) for the full list of supported platforms and provider-specific configuration.\n\n## Live examples\n\nThese are deployed to Cloudflare Workers and updated on every push to `main`:\n\n| Example | Description | URL |\n| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| App Router Playground | [Vercel's Next.js App Router Playground](https://github.com/vercel/next-app-router-playground) running on vinext | [app-router-playground.vinext.workers.dev](https://app-router-playground.vinext.workers.dev) |\n| Hacker News | HN clone (App Router, RSC) | [hackernews.vinext.workers.dev](https://hackernews.vinext.workers.dev) |\n| Nextra Docs | Nextra docs site (MDX, App Router) | [nextra-docs-template.vinext.workers.dev](https://nextra-docs-template.vinext.workers.dev) |\n| App Router (minimal) | Minimal App Router on Workers | [app-router-cloudflare.vinext.workers.dev](https://app-router-cloudflare.vinext.workers.dev) |\n| Pages Router (minimal) | Minimal Pages Router on Workers | [pages-router-cloudflare.vinext.workers.dev](https://pages-router-cloudflare.vinext.workers.dev) |\n| Static export | [Hybrid App/Pages Router site](examples/static-export) served as assets only | [static-export.vinext.workers.dev](https://static-export.vinext.workers.dev) |\n| RealWorld API | REST API routes example | [realworld-api-rest.vinext.workers.dev](https://realworld-api-rest.vinext.workers.dev) |\n| Benchmarks Dashboard | Build performance tracking over time (D1-backed) | [vinext.dev/benchmarks](https://vinext.dev/benchmarks) |\n| App Router + Nitro | App Router deployed via Nitro (multi-platform) | [examples/app-router-nitro](examples/app-router-nitro) |\n\n## API coverage\n\n~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features, plus Partial Prerendering and Cache Components. Next.js 16 reworked PPR into `\"use cache\"`; vinext implements that directive for file-level and function-level caching, but full `cacheComponents` behavior is still incomplete — see [Known gaps we're working on](#known-gaps-were-working-on).\n\n> ✅ = full implementation | 🟡 = partial (runtime behavior correct, some build-time optimizations missing) | ⬜ = intentional stub/no-op\n\n### Module shims\n\nEvery `next/*` import is shimmed to a Vite-compatible implementation.\n\n| Module | | Notes |\n| ------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `next/link` | ✅ | All props including `prefetch` (IntersectionObserver), `onNavigate`, scroll restoration, `basePath`, `locale` |\n| `next/image` | 🟡 | Remote images via [@unpic/react](https://unpic.pics) (28 CDNs). Local images via `` + srcSet. No build-time optimization/resizing |\n| `next/head` | ✅ | SSR collection + client-side DOM manipulation |\n| `next/router` | ✅ | `useRouter`, `Router` singleton, events, client-side navigation, SSR context, i18n |\n| `next/navigation` | ✅ | `usePathname`, `useSearchParams`, `useParams`, `useRouter`, `redirect`, `notFound`, `forbidden`, `unauthorized` |\n| `next/server` | ✅ | `NextRequest`, `NextResponse`, `NextURL`, cookies, `userAgent`, `after`, `connection`, `URLPattern` |\n| `next/headers` | ✅ | Async `headers()`, `cookies()`, `draftMode()` |\n| `next/dynamic` | ✅ | `ssr: true`, `ssr: false`, `loading` component |\n| `next/script` | ✅ | All 4 strategies (`beforeInteractive`, `afterInteractive`, `lazyOnload`, `worker`) |\n| `next/font/google` | 🟡 | Runtime CDN loading. No self-hosting, font subsetting, or fallback metrics |\n| `next/font/local` | 🟡 | Runtime `@font-face` injection. Not extracted at build time |\n| `next/og` | ✅ | OG image generation via `@vercel/og` (Satori + resvg) |\n| `next/cache` | ✅ | `revalidateTag`, `revalidatePath`, `unstable_cache`, pluggable `CacheHandler`, `\"use cache\"` with `cacheLife()` and `cacheTag()` |\n| `next/form` | ✅ | GET form interception + POST server action delegation |\n| `next/legacy/image` | ✅ | Translates legacy props to modern Image |\n| `next/error` | ✅ | Default error page component |\n| `next/config` | ✅ | `getConfig` / `setConfig` |\n| `next/document` | ✅ | `Html`, `Head`, `Main`, `NextScript` |\n| `next/constants` | ✅ | All phase constants |\n| `next/amp` | ⬜ | No-op (AMP is deprecated) |\n| `next/web-vitals` | ⬜ | No-op (use the `web-vitals` library directly) |\n\n### Routing\n\n| Feature | | Notes |\n| -------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------ |\n| File-system routing (`pages/`) | ✅ | Automatic scanning with hot-reload on file changes |\n| File-system routing (`app/`) | ✅ | Pages, routes, layouts, templates, loading, error, not-found, forbidden, unauthorized |\n| Dynamic routes `[param]` | ✅ | Both routers |\n| Catch-all `[...slug]` | ✅ | Both routers |\n| Optional catch-all `[[...slug]]` | ✅ | Both routers |\n| Route groups `(group)` | ✅ | URL-transparent, layouts still apply |\n| Parallel routes `@slot` | ✅ | Discovery, layout props, `default.tsx`, inherited slots |\n| Intercepting routes | ✅ | `(.)`, `(..)`, `(..)(..)`, `(...)` conventions |\n| Route handlers (`route.ts`) | ✅ | Named HTTP methods, auto OPTIONS/HEAD, cookie attachment |\n| Middleware | ✅ | `middleware.ts` and `proxy.ts` (Next.js 16). Matcher patterns (string, array, regex, `:param`, `:path*`, `:path+`) |\n| i18n routing | 🟡 | Pages Router locale prefix, Accept-Language detection, NEXT_LOCALE cookie. No domain-based routing |\n| `basePath` | ✅ | Applied everywhere — URLs, Link, Router, navigation hooks |\n| `trailingSlash` | ✅ | 308 redirects to canonical form |\n\n### Server features\n\n| Feature | | Notes |\n| ------------------------------------------ | --- | ------------------------------------------------------------------------------------------- |\n| SSR (Pages Router) | ✅ | Streaming, `_app`/`_document`, `__NEXT_DATA__`, hydration |\n| SSR (App Router) | ✅ | RSC pipeline, nested layouts, streaming, nav context for client components |\n| `getStaticProps` | ✅ | Props, redirect, notFound, revalidate |\n| `getStaticPaths` | ✅ | `fallback: false`, `true`, `\"blocking\"` |\n| `getServerSideProps` | ✅ | Full context including locale |\n| ISR | ✅ | Stale-while-revalidate, pluggable `CacheHandler`, background regeneration |\n| Server Actions (`\"use server\"`) | ✅ | Action execution, FormData, re-render after mutation, `redirect()` in actions |\n| React Server Components | ✅ | Via `@vitejs/plugin-rsc`. `\"use client\"` boundaries work correctly |\n| Streaming SSR | ✅ | Both routers |\n| Metadata API | ✅ | `metadata`, `generateMetadata`, `viewport`, `generateViewport`, title templates |\n| `generateStaticParams` | ✅ | With `dynamicParams` enforcement |\n| Metadata file routes | ✅ | sitemap.xml, robots.txt, manifest, favicon, OG images (static + dynamic) |\n| Static export (`output: 'export'`) | ✅ | Generates static HTML/JSON for all routes |\n| Standalone output (`output: 'standalone'`) | ✅ | Generates `dist/standalone` with `server.js`, build artifacts, and runtime deps |\n| `connection()` | ✅ | Forces dynamic rendering |\n| `\"use cache\"` directive | ✅ | File-level and function-level. `cacheLife()` profiles, `cacheTag()`, stale-while-revalidate |\n| `instrumentation.ts` | ✅ | `register()` and `onRequestError()` callbacks |\n| Route segment config | 🟡 | `revalidate`, `dynamic`, `dynamicParams`. `runtime` and `preferredRegion` are ignored |\n\n### Configuration\n\n| Feature | | Notes |\n| ------------------------------------------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `next.config.js` / `.ts` / `.mjs` | ✅ | Function configs, phase argument |\n| `rewrites` / `redirects` / `headers` | ✅ | All phases, param interpolation |\n| Environment variables (`.env*`, `NEXT_PUBLIC_*`) | ✅ | Auto-loads Next.js-style dotenv files; only public vars are inlined |\n| `images` config | 🟡 | Parsed but not used for optimization |\n| `experimental.optimizePackageImports` | ✅ | Rewrites barrel imports to direct sub-module imports in RSC/SSR environments. A default set (lucide-react, date-fns, radix-ui, antd, MUI, and others) are always optimized. Add package names here to extend the list. |\n| `vinext({ nextConfig })` | ✅ | Inline Next-style config from `vite.config.*`. Supports object-form and function-form config. When provided, this overrides root `next.config.*`. |\n| `vinext({ react: { compiler: true } })` | ✅ | React Compiler auto memoization. Needs `@vitejs/plugin-react` 6.1+ and the optional `oxc-transform-react` package. |\n\n### React Compiler\n\nvinext auto-registers `@vitejs/plugin-react`, so the React Compiler is enabled through the same `react` option:\n\n```ts\nimport { defineConfig } from \"vite\";\nimport vinext from \"vinext\";\n\nexport default defineConfig({\n plugins: [vinext({ react: { compiler: true } })],\n});\n```\n\nThe transform itself ships separately, so install it alongside:\n\n```bash\nnpm install -D oxc-transform-react\n```\n\nThis requires `@vitejs/plugin-react` 6.1.0 or newer. Older versions accept the option and drop it, so vinext fails with an actionable error instead of leaving the compiler silently disabled. The compiler runs on the client environment only.\n\nOne caveat: modules whose JSX is lowered earlier in the pipeline are not memoized. Those build and behave correctly, they just miss auto memoization:\n\n- JSX in plain `.js` files, which `vinext:jsx-in-js` compiles first so the compiler can parse them at all. Rename to `.jsx` or `.tsx` to get memoization.\n- Components using `