Skip to main content

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.

The vinext CLI is a drop-in replacement for the next command that runs your Next.js app on Vite instead of webpack.

​
Installation

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

​
Quick Start

vinext dev      # Start development server
vinext build    # Build for production
vinext start    # Start production server

​
Available Commands

The vinext CLI provides these commands:
CommandDescription
devStart development server with Vite and HMR
buildBuild for production (auto-detects App/Pages Router)
startServe production build
deployOne-command deployment to Cloudflare Workers
initMigrate an existing Next.js project to vinext
checkScan project for compatibility issues
lintRun linter (delegates to eslint or oxlint)

​
Global Options

These options work with all commands:
​
--help
flag
Show help for a command
vinext --help
vinext dev --help
​
--version
flag
Show version information
vinext --version
# vinext v0.0.1

​
Version Information

Check the installed vinext and Vite versions: 
vinext --version
During execution, vinext will show the Vite version being used: 
vinext dev
# vinext dev  (Vite 6.0.0)

​
Configuration

vinext requires minimal configuration:

​
Automatic Configuration (No Config File)

If you don’t have a vite.config.ts file, vinext auto-configures everything:
  • Registers the vinext plugin automatically
  • Auto-detects App Router (app/ directory) and registers RSC plugin
  • Deduplicates React packages (prevents “Invalid hook call” errors)
  • Works with both app/ and src/app/, pages/ and src/pages/

​
Manual Configuration (vite.config.ts)

For custom setups, create a vite.config.ts: 
import { defineConfig } from 'vite'
import vinext from 'vinext'

export default defineConfig({
  plugins: [vinext()],
})
If you have a config file, vinext uses it instead of auto-configuration.

​
Compatibility Flags

vinext accepts some Next.js flags for drop-in compatibility, but ignores them:
​
--turbopack
flag
Accepted for compatibility with Next.js scripts. No-op (Vite is always used).
​
--experimental-https
flag
Accepted for compatibility. No-op. Configure HTTPS in vite.config.ts if needed.

​
Environment Variables

vinext respects these environment variables:
VariableDescriptionDefault
PORTProduction server port (used by vinext start)3000
CLOUDFLARE_API_TOKENAPI token for Cloudflare Workers deployment-

​
Development vs Production

​
Development Mode (vinext dev)

  • App Router: Uses Vite dev server with HMR for React Server Components
  • Pages Router: Server-side renders on each request with full reload on changes
  • Module resolution: Resolves Vite from your project’s node_modules to prevent dual instances

​
Production Mode (vinext build + vinext start)

  • App Router: Multi-environment build (RSC, SSR, Client) using createBuilder()
  • Pages Router: Separate client and server builds
  • Output: dist/client/ (static assets), dist/server/ (SSR entry)
  • Optimizations: Code splitting, tree-shaking, minification

​
Router Detection

vinext automatically detects your router type: 
# Detects app/ or src/app/
vinext dev
# vinext dev  (Vite 6.0.0)
# [App Router detected]

​
Common Workflows

​
Local Development

# Start dev server
vinext dev

# Custom port
vinext dev --port 4000

# Custom hostname
vinext dev --hostname 0.0.0.0

​
Production Build and Deploy

# Build and run locally
vinext build
vinext start

# Build and deploy to Cloudflare Workers
vinext deploy

# Deploy preview environment
vinext deploy --preview

​
Migrating an Existing Project

# Check compatibility first
vinext check

# Run automated migration
vinext init

# Start dev server
npm run dev:vinext

​
Module Resolution

vinext dynamically resolves Vite from your project’s node_modules at runtime, not from vinext’s own dependencies. This prevents dual Vite instances when using npm link or bun link during development. If Vite cannot be resolved from your project, vinext falls back to its bundled copy.

​
Next Steps

dev Command

Start the development server

build Command

Build for production

deploy Command

Deploy to Cloudflare Workers

check Command

Check project compatibility

Build docs developers (and LLMs) love

Get started for freeTalk to us