vinext

0.0.44 verified Mon Apr 27 auth: no javascript

A drop-in replacement for the Next.js CLI that runs on Vite instead of the Next.js custom server. Currently at v0.0.44 (pre-1.0, active development with frequent releases every few days). It reimplements the Next.js API surface on top of Vite, supporting both Pages Router and App Router, with HMR, build, deploy to Cloudflare Workers, and standalone self-host output. Key differentiators: AI-assisted development (Claude Code generated most of the code), tight Cloudflare integration. Caveat: experimental, buggy, and lacks full Next.js compatibility. Requires Node >=22 and Vite 7 or 8.

Common errors

error Error: Cannot find module 'vite' ↓

cause Missing peer dependency: vite is not installed.

fix

Run: npm install -D vite@^7.0.0

error Error: @vitejs/plugin-react is required for vinext to run ↓

cause Missing or incompatible @vitejs/plugin-react version.

fix

Run: npm install -D @vitejs/plugin-react@^5.1.4 || ^6.0.0

error Error: Node.js version 20.x.x is not supported. Vinext requires Node.js >=22. ↓

cause Node.js version too old.

fix

Upgrade Node.js to v22 or later (e.g., using nvm: nvm install 22)

Warnings

breaking Requires Node >=22; older Node versions (e.g., 18, 20) will fail to run vinext. ↓

fix Upgrade Node to v22 or later.

gotcha vinext uses HOST environment variable for bind address, not HOSTNAME (which Next.js uses). This can cause port binding failures in deployment scripts that rely on HOSTNAME. ↓

fix Set HOST instead of HOSTNAME in your environment/deployment config.

gotcha Standalone build output differs from Next.js standalone; vinext emits to dist/standalone/ and expects different startup command (node dist/standalone/server.js). ↓

fix Update deployment to use 'node dist/standalone/server.js' and set PORT/HOST env vars.

deprecated The init command may prompt for options that are not yet implemented or have changed (e.g., --port may not work as expected). ↓

fix Use --help to check current options; prefer manual migration if automated init fails.

gotcha Not all Next.js features are supported; vinext is experimental and may have bugs with edge cases like intercepting routes, custom error pages, or advanced caching. ↓

fix Run 'vinext check' before migrating to identify unsupported features.

Install

npm install vinext

yarn add vinext

pnpm add vinext

Imports

vinext CLI
wrong
```
npx next dev
```
correct
```
npx vinext dev
```
Scripts should use 'vinext' instead of 'next'. Running 'next dev' will use the original Next.js CLI, not vinext.
Package scripts (package.json)
wrong
```
"dev": "next dev"
```
correct
```
"dev": "vinext dev"
```
Replace 'next' with 'vinext' in npm scripts. The CLI is a drop-in replacement for the 'next' command.
vinext.check() (programmatic API)
wrong
```
const { check } = require('vinext')
```
correct
```
import { check } from 'vinext'
```
vinext is ESM-only; no CommonJS require support. Use dynamic import() if needed in CJS contexts.

Quickstart

Installs vinext and peer dependencies, replaces next CLI with vinext in package.json scripts, and provides CLI usage for dev/build/start.

// Install vinext and its peer dependencies
npm install -D vinext vite @vitejs/plugin-react

// If using App Router, also install:
npm install -D @vitejs/plugin-rsc react-server-dom-webpack

// In package.json, replace 'next' with 'vinext':
// {
//   "scripts": {
//     "dev": "vinext dev",
//     "build": "vinext build",
//     "start": "vinext start"
//   }
// }

// Then run:
// vinext dev     - Development server with HMR
// vinext build   - Production build
// vinext start   - Start local production server

// For existing Next.js projects, check compatibility first:
// npx vinext check

// To migrate automatically (using AI skill):
// npx skills add cloudflare/vinext
// Then in your AI tool: "migrate this project to vinext"