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.

Starts a local development server with Vite’s fast HMR (Hot Module Replacement).

​
Usage

vinext dev [options]

​
Options

​
--port
number
default:"3000"
Port to listen on. Can also use the short form -p.
vinext dev --port 4000
vinext dev -p 4000
​
--hostname
string
default:"localhost"
Hostname to bind to. Can also use the short form -H.
vinext dev --hostname 0.0.0.0
vinext dev -H 0.0.0.0
Use 0.0.0.0 to expose the server on your local network.
​
--turbopack
flag
Accepted for compatibility with Next.js. No-op (Vite is always used).
vinext dev --turbopack
​
--help
flag
Show help for this command. Can also use -h.
vinext dev --help

​
Behavior

​
Router Detection

vinext automatically detects your router type:
  • App Router: Detects app/ or src/app/ directory
  • Pages Router: Detects pages/ or src/pages/ directory (when no app/ exists)
The dev server behavior differs based on router: 
// Uses @vitejs/plugin-rsc for React Server Components
// Hot reloads Server Components without full refresh
// Client Components use Vite's standard HMR

export default function Page() {
  // This component hot reloads on save
  return <div>Hello from RSC</div>
}

​
Vite Integration

vinext runs Vite’s dev server under the hood with these features:
  • Fast cold start: No bundling required, uses native ESM
  • Instant HMR: Changes reflect immediately without full reload
  • Optimized dependencies: Pre-bundles dependencies with esbuild
  • Module deduplication: Prevents “Invalid hook call” errors by deduplicating React packages

​
Configuration Loading

The dev server loads configuration in this order:
  1. User’s vite.config.ts: If present, uses your custom config
  2. Auto-configuration: If no config file exists, vinext generates one automatically:
    • Registers vinext() plugin
    • Auto-detects and registers @vitejs/plugin-rsc for App Router
    • Sets up React deduplication

​
Module Resolution

vinext dynamically resolves Vite from your project’s node_modules, not from vinext’s installation directory. This prevents dual Vite instances when using npm link or bun link for local development. 
// From cli.ts:48-66
async function loadVite(): Promise<ViteModule> {
  if (_viteModule) return _viteModule;

  const projectRoot = process.cwd();
  let vitePath: string;

  try {
    // Resolve "vite" from the project root, not from vinext's location
    const require = createRequire(path.join(projectRoot, "package.json"));
    vitePath = require.resolve("vite");
  } catch {
    // Fallback: use the Vite that ships with vinext
    vitePath = "vite";
  }

  const vite = await import(vitePath);
  _viteModule = vite;
  return vite;
}

​
Examples

​
Basic Usage

Start dev server on default port (3000): 
vinext dev
Output: 
vinext dev  (Vite 6.0.0)

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --hostname 0.0.0.0 to expose

​
Custom Port

Start dev server on port 4000: 
vinext dev --port 4000
Or using the short form: 
vinext dev -p 4000

​
Expose on Local Network

Make the dev server accessible from other devices on your network: 
vinext dev --hostname 0.0.0.0
Output: 
vinext dev  (Vite 6.0.0)

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.1.100:3000/

​
Custom Port and Hostname

Combine options: 
vinext dev --port 8080 --hostname 0.0.0.0
Short form: 
vinext dev -p 8080 -H 0.0.0.0

​
Using with npm Scripts

Add to your package.json: 
{
  "scripts": {
    "dev": "vinext dev",
    "dev:custom": "vinext dev --port 4000"
  }
}
Then run: 
npm run dev
npm run dev:custom

​
Configuration File

If you don’t have a vite.config.ts, vinext auto-configures everything: 
vinext dev
# No vite.config.ts needed — vinext handles it

​
Custom Configuration

Create a vite.config.ts for custom setups: 
import { defineConfig } from 'vite'
import vinext from 'vinext'

export default defineConfig({
  plugins: [vinext()],
  server: {
    port: 3000,
    host: 'localhost',
    // Add custom Vite server config here
  },
})
If you have a vite.config.ts, vinext uses it instead of auto-configuration. Make sure to include the vinext() plugin.

​
Development Features

​
Hot Module Replacement (HMR)

vinext provides instant HMR for:
  • Client Components: Full React Fast Refresh support
  • Server Components (App Router): Selective updates without full page reload
  • Styles: CSS/SCSS changes apply instantly
  • Static assets: Image/font changes reflect immediately

​
TypeScript

vinext fully supports TypeScript with no additional configuration: 
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page',
}

export default function Page() {
  return <div>TypeScript works out of the box</div>
}

​
Environment Variables

Access environment variables in your code: 
// Client-side (must be prefixed with NEXT_PUBLIC_)
const apiUrl = process.env.NEXT_PUBLIC_API_URL

// Server-side (any variable)
const secret = process.env.API_SECRET
Load from .env.local: 
NEXT_PUBLIC_API_URL=https://api.example.com
API_SECRET=secret123

​
Troubleshooting

​
Port Already in Use

If port 3000 is already in use: 
vinext dev --port 3001
Or stop the process using port 3000: 
# Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

​
Module Not Found Errors

If you see “Module not found” errors, ensure dependencies are installed: 
npm install
For App Router projects, ensure @vitejs/plugin-rsc is installed: 
npm install -D @vitejs/plugin-rsc

​
Invalid Hook Call Error

This usually indicates duplicate React instances. vinext automatically deduplicates React, but if you still see this error:
  1. Clear node_modules and reinstall: 
    rm -rf node_modules package-lock.json
npm install
  2. If using npm link, ensure you’re resolving React from the project: 
    cd your-project
npm link react react-dom

​
Performance

vinext dev server is significantly faster than Next.js:
  • Cold start: 2-3x faster (no bundling required)
  • HMR: 10-50x faster (native ESM vs webpack HMR)
  • Memory usage: Lower (no webpack compilation overhead)

​
Next Steps

build Command

Build your app for production

Configuration

Configure vinext with vite.config.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us