Nextvi

1.1.0 verified Fri May 01 auth: no javascript

Nextvi (next-vite-dev v1.1.0) lets you run a lightweight Vite dev server alongside Next.js, consuming src/app/ pages without modifying any business code. It auto-generates react-router routes from the Next.js app directory, handles async server components by converting them to sync, and provides shims for next/link, next/image, and next/navigation. Target audience: Next.js developers suffering from high memory usage or slow HMR in large projects. Release cadence: early-stage, active development. Differentiator: zero-config, zero-code-change Vite integration with automatic route generation and wrapper overrides for server-fetch pages.

Common errors

error Cannot find module 'virtual:auto-routes' ↓

cause Virtual module is only available during Vite dev/build with the plugin enabled.

fix

Ensure nextvi() is added to plugins in vite.config.ts and that you are running 'pnpm vite' (not 'pnpm dev').

error Failed to resolve import 'next/link' from 'src/app/page.tsx' ↓

cause In Vite mode, 'next/link' shim is not found if the package is not installed (it is a peer dep via Next.js).

fix

Add 'next' as a devDependency or ensure it is hoisted: pnpm add -D next

error [plugin:nextvi] No Vite entry found at /vite/entry.tsx ↓

cause The entry file does not exist at the expected location.

fix

Create the file vite/entry.tsx at the project root with correct content.

error TypeError: Cannot read properties of undefined (reading 'params') ↓

cause Async server component without wrapper; params is undefined in client.

fix

Create a wrapper in vite/wrappers/ mirroring the route path that uses useParams() from next/navigation.

Warnings

breaking Requires react-router-dom v6+. BrowserRouter or RouterProvider must be used; v5 is not supported. ↓

fix Upgrade to react-router-dom v6+ and use createBrowserRouter or BrowserRouter v6.

breaking Vite entry file must be at /vite/entry.tsx (root-relative). Custom path not supported yet. ↓

fix Place entry.tsx in vite/ directory at project root.

deprecated Plugin option 'include' is deprecated; use 'customEntries' for additional directories. ↓

fix Remove 'include' and pass custom directories to 'customEntries' array if needed.

gotcha Server components with async fetch will fail in Vite mode unless wrapped via vite/wrappers/. ↓

fix Create a wrapper file under vite/wrappers/ mirroring the route path, using client-side fetch.

gotcha Only pages inside src/app/ are auto-routed. Pages outside (e.g., pages/) are ignored. ↓

fix Move pages into src/app/ directory or manually add vite routes.

Install

npm install next-vite-dev

yarn add next-vite-dev

pnpm add next-vite-dev

Imports

nextvi (default)
wrong
```
const nextvi = require('next-vite-dev')
```
correct
```
import nextvi from 'next-vite-dev'
```
ESM-only package. Use import syntax; requires Node >= 16.
routes (virtual module)
wrong
```
import routes from 'virtual:auto-routes'
```
correct
```
import { routes } from 'virtual:auto-routes'
```
This is a virtual module provided by the Vite plugin, not a real file. Named export required.
next/link shim
```
import Link from 'next/link'
```
Shim is automatic; no special import needed. But when running under Vite, it resolves to a built-in client implementation. No change to existing code.
next/navigation shim
```
import { useRouter } from 'next/navigation'
```
Shim is automatic; works in both Next.js and Vite modes. No migration needed.
next/image shim
```
import Image from 'next/image'
```
Shim is automatic; uses a regular img tag under Vite. No code changes needed.

Quickstart

Initialize Nextvi by adding the Vite plugin, creating index.html, Vite entry, and ViteApp component to auto-generate routes from your existing Next.js app directory.

// vite.config.ts
import { defineConfig } from 'vite'
import nextvi from 'next-vite-dev'

export default defineConfig({
  plugins: [nextvi()],
})

// index.html (project root)
<!DOCTYPE html>
<html lang="en">
  <head><meta charset="UTF-8" /><title>My App</title></head>
  <body>
    <div id="root"></div>
    <script type="module" src="/vite/entry.tsx"></script>
  </body>
</html>

// vite/entry.tsx
import '../src/app/globals.css'
import ReactDOM from 'react-dom/client'
import ViteApp from './ViteApp'

ReactDOM.createRoot(document.getElementById('root')!).render(<ViteApp />)

// vite/ViteApp.tsx
import { Suspense } from 'react'
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
import { routes } from 'virtual:auto-routes'

const router = createBrowserRouter(routes)

export default function ViteApp() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <RouterProvider router={router} />
    </Suspense>
  )
}