# vinext: running Next.js apps on Vite with Cloudflare Workers as the main target

> vinext reimplements the Next.js API surface on Vite instead of consuming next build output. It covers both routers and RSC, but the README calls it a beta that is not yet a drop-in replacement.

**cloudflare/vinext** — Vite plugin that reimplements the Next.js API surface — deploy anywhere

- Repository: https://github.com/cloudflare/vinext
- Website: https://vinext.dev
- Stars: 8,975 · Forks: 420
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudflare-vinext

## The problem vinext solves: Next.js semantics without the Next.js build

Next.js couples its framework API to its own compiler and build pipeline. If you want the App Router, React Server Components, Server Actions, middleware and the next/* modules, you generally also accept next build and the deployment shapes it produces. vinext takes the other route. It reimplements the Next.js API surface on top of Vite rather than consuming next build output, so the framework behavior is reproduced by a plugin rather than inherited from the original toolchain.

The audience is narrow and specific. This is for teams that already have a Next.js application and want to run it somewhere the standard pipeline does not reach cleanly, with Cloudflare Workers as the primary deployment target. It is also for people who want Vite's development server and plugin ecosystem around a Next.js-shaped app. It is not for greenfield projects with no Next.js investment, since the entire value proposition is compatibility with code you already wrote.

The README is blunt about maturity: vinext is under active development, supports substantial Next.js applications today, and is not yet a drop-in replacement for every application or production workload. That sentence should set expectations for everything below.

## How the Vite plugin reproduces the Next.js API surface

The mechanism is a set of shims and build environments rather than a port of Next.js internals. vinext auto-detects your app/ or pages/ directory, loads next.config.js, and configures Vite automatically. No vite.config.ts is required for basic usage, which means the plugin is doing the routing, environment wiring and module resolution on your behalf.

For the App Router, vinext build is described as a multi-environment build covering RSC, SSR and client. That split is what makes React Server Components work under Vite: the server component graph, the SSR pass and the browser bundle are separate compilation targets, and react-server-dom-webpack plus @vitejs/plugin-rsc are the pieces the README tells you to install for that mode. The Pages Router path is simpler and does not require those two packages.

The next/* modules are reimplemented rather than imported from the real package. next/link, next/image, next/navigation, next/headers, next/cache and the Metadata API are all listed as working today. That is the part of the design that matters most in practice, because these modules are what application code touches directly. Route handlers, middleware, static generation, ISR and output: "export" are also covered. The repository layout supports this reading: there is a scripts/sync-next-types.mjs and a scripts/check-shim-types.mjs, and the check script runs both, which suggests the shim types are kept in sync with upstream Next.js types and verified in CI rather than hand-maintained once.

Deployment is a separate package. @vinext/cloudflare handles bindings, cache adapters and image optimization on Workers, and there is a @cloudflare/workers-response-store package in the same release train. Node.js and other platforms are available with different levels of support, which in practice means Cloudflare Workers is where the integration is deepest and where you should expect the fewest surprises.

## Installing vinext and migrating a Next.js project

The README recommends the official setup commands over manual installation, because they configure dependencies, scripts, Vite and your deployment target together. For a new project, create-vinext-app is the entry point:

```bash
pnpm create vinext-app@latest my-app
```

That scaffolds a project already wired for vinext. You should end up with a working dev server and a deployment target selected, without editing Vite configuration yourself.

For an existing Next.js application, the migration command is vinext init:

```bash
npx vinext init
```

It prompts for a deployment target and defaults to Cloudflare. Non-interactive callers pass --platform=cloudflare or --platform=node explicitly, and the README notes that agents must ask the user which target they want before passing the flag. Other options are --port (default 3001), --skip-check and --force. Before running it, the README suggests vinext check, which scans your app for known compatibility issues. That ordering matters: check is read-only reconnaissance, init changes files.

If you prefer to wire things up by hand, the manual path is four packages. The base install is:

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

App Router projects need two more, and only those projects:

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

Then replace next with vinext in your scripts. The README gives this exact shape for package.json:

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

After that, vinext dev starts the development server with HMR, vinext build produces the production build, and npx @vinext/cloudflare deploy builds and deploys to Cloudflare Workers. The CLI also accepts -p / --port, -H / --hostname, and --turbopack, which the README says is accepted but is a no-op. If your next.config.* sets output: "standalone", the build emits a self-hosting bundle at dist/standalone/ that you start with node dist/standalone/serve.

## Where vinext is not a drop-in replacement yet

The known gaps section is the most useful part of the README, and it is worth reading as a list of things that will break rather than a roadmap. Cache Components and Partial Prerendering are the largest. "use cache" is partially implemented, but full cacheComponents behavior is incomplete: cache profiles, tags, partial shells, resume behavior, prefetching and some dev and build cache semantics do not match Next.js in every case. If your application leans on PPR for streaming shells, this is the wrong tool right now.

Build-time image and font optimization is the second gap. Images can be optimized at request time on Cloudflare, but vinext does not reproduce Next.js's complete build-time image pipeline. Google Fonts load from the CDN, and local font CSS is injected at runtime rather than extracted during the build. That changes your first-paint characteristics and your caching story, and it is a deliberate trade-off rather than an oversight.

The third gap is the one most likely to bite during development. Native modules including sharp, resvg, satori, lightningcss and @napi-rs/canvas can fail in Vite's RSC development environment, though production builds support more of these cases than development mode. A failure that only appears under vinext dev and disappears under vinext build is exactly the kind of thing that wastes an afternoon. Beyond that, runtime and preferredRegion route config are currently ignored, and the README warns that some recently introduced or undocumented Next.js behavior may not be reproduced at all. Ignored route config is silent: nothing errors, the setting simply has no effect.

## vinext vs OpenNext: two different answers to the same question

The obvious comparison is OpenNext, and the difference is architectural rather than cosmetic. OpenNext takes Next.js build output and adapts it to run on a target platform. It works with the real next build, so whatever Next.js produces is what you deploy, and compatibility tracks upstream releases. The cost is that you inherit Next.js's build pipeline and its assumptions about the runtime.

vinext inverts that. It reimplements the Next.js API surface on Vite instead of consuming next build output, which is why it can target Workers as a first-class runtime rather than an adaptation layer, and why Cloudflare's integration (bindings, cache adapters, image optimization) is described as the deepest. The cost is that compatibility is a moving target maintained by the vinext project. Every Next.js feature has to be reproduced, and the README's gap list is the visible edge of that work.

If you want the smallest behavioral delta from stock Next.js, the adapter approach is the more conservative choice. If you want Vite's dev server and a Workers-native deployment path, and you can absorb compatibility gaps in the specific features you use, vinext is the more direct route. The two are not interchangeable, and the deciding factor is which set of features your application actually exercises.

## Beta releases, licence and what an upgrade costs

Every package in the current release train is on a beta version: vinext@1.0.0-beta.11, @vinext/cloudflare@1.0.0-beta.9 and @cloudflare/workers-response-store@0.1.0-beta.1, all published on 2026-09-21. The repository uses Changesets, with a .changeset/ directory and a changeset script in the root package.json, so versioning and changelogs are managed per package rather than as one monolith. In practice that means vinext and @vinext/cloudflare can move independently, and a deploy package bump may arrive without a framework bump.

The maintenance signal is strong: the last push was on 2026-09-21, the same day as the releases, and the repository is not archived. The README itself says the project is under active development. That cuts both ways for upgrade cost. You get fixes quickly, and you also get churn on a beta line where breaking changes are expected rather than exceptional. Pinning exact versions and reading the changeset before bumping is the realistic posture while the version number starts with 1.0.0-beta.

The licence is MIT, which is permissive and imposes no copyleft obligation on your application. That is the whole of what can be said here; questions about your specific dependency graph, bundled assets or attribution requirements belong with your own legal review, not with this article.

## Conclusion

Adopt vinext if you have a Next.js app that leans on the Pages Router or the core App Router features and you want Cloudflare Workers as the deployment target, and run vinext check on a branch before anything else. Do not adopt it if you depend on Cache Components, Partial Prerendering, build-time image and font extraction, or native modules such as sharp and satori in App Router development, because the README lists those as open compatibility areas rather than finished work. Verify two things first: that your next.config.js settings survive vinext's automatic loading, and that your package.json scripts no longer call next. The project is at 1.0.0-beta.11, so treat every version bump as a migration until the beta line ends.

## FAQ

### What are the key differences between OpenNext and vinext?

OpenNext adapts the output of the real Next.js build to a target platform, while vinext reimplements the Next.js API surface on Vite rather than consuming next build output. That is why vinext can treat Cloudflare Workers as a primary target with its own bindings, cache adapters and image optimization, and why its compatibility with Next.js features is maintained by the vinext project instead.

### What is vinext?

vinext is a Vite plugin that reimplements the Next.js API surface, supporting 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 is the primary deployment target, with Node.js and other platforms available at different levels of support.

### Is vinext production ready?

The README states that vinext supports substantial Next.js applications today but is not yet a drop-in replacement for every application or production workload, and that compatibility gaps should be expected, especially in newer App Router features. It advises evaluating vinext against your own application before adopting it.

### Can I use Next.js with Cloudflare Workers?

vinext is built for exactly that: Cloudflare Workers is its primary deployment target, with bindings, cache adapters and image optimization support, and the deploy command is npx @vinext/cloudflare deploy. Node.js and other platforms are also available with different levels of support.

## Sources

- [cloudflare/vinext on GitHub](https://github.com/cloudflare/vinext)
- [License: MIT](https://github.com/cloudflare/vinext/blob/main/LICENSE)
- [Project website](https://vinext.dev)
- [README](https://github.com/cloudflare/vinext/blob/main/README.md)
- [Releases](https://github.com/cloudflare/vinext/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudflare-vinext