vavite

6.2.1 verified Fri May 01 auth: no javascript

vavite is a Vite plugin for developing and building server-side applications, using Vite as the transpiler/bundler. It enables using Vite's SSR capabilities for general server-side code (TypeScript, JSX) without extra tools like ts-node. Current stable version is 6.2.1, supporting Vite 7 or 8 (peer dependency). Key differentiators: simplifies SSR workflow, supports handler and server entry types, provides HMR for server code. Rewritten in v6 with a simplified API, server-side HMR, and separate server mode (e.g. for Bun.serve).

Common errors

error Cannot find module 'vavite' or its corresponding type declarations. ↓

cause Missing installation or misconfigured tsconfig paths.

fix

Install vavite as dev dependency: npm install --save-dev vavite. Ensure tsconfig.json includes 'node' in types or 'moduleResolution' is 'bundler'.

error The requested module 'vavite' does not provide an export named 'default' ↓

cause Using default import after v3.0.0 which switched to named exports.

fix

Change import vavite from 'vavite' to import { vavite } from 'vavite'.

error [vite] Internal server error: Cannot read properties of undefined (reading 'on') ↓

cause Missing or misconfigured entry file. vavite expects a default export handler or server entry.

fix

Ensure src/entry.server.{js,ts} exists with a default export and correct entry type in config.

error ERR_UNSUPPORTED_DIR_IMPORT from node_modules/vavite ↓

cause Node.js version mismatch or ESM/CJS conflict. vavite requires Node.js ESM support.

fix

Ensure your project is ESM (type: module in package.json) and Node.js >=18.

Warnings

breaking v3.0.0 changed from default export to named export: import vavite from 'vavite' becomes import { vavite } from 'vavite'. ↓

fix Change to named import: import { vavite } from 'vavite'.

breaking v6.0.0 is a complete rewrite with a simplified API. Old plugin options and entry types are deprecated. ↓

fix Consult the migration notes at https://github.com/cyco130/vavite#migrating-from-v5.

deprecated The `runnable-handler` and `runnable-server` entry types are replaced by a single `handler` entry in v6. ↓

fix Use `type: 'handler'` in entries configuration.

gotcha In handler entries, the default export is used for dev mode, but for production you must explicitly start the server. The `import.meta.env.COMMAND` check is required to avoid starting the server in dev mode. ↓

fix Wrap production server start with `if (import.meta.env.COMMAND === 'build')`.

gotcha TypeScript builds may fail if triple-slash references are missing: `/// <reference types="vite/client" />` and `/// <reference types="vavite/types" />`. ↓

fix Add the triple-slash directives at the top of your entry file, or include them in tsconfig.json types array.

Install

npm install vavite

yarn add vavite

pnpm add vavite

Imports

vavite
wrong
```
import vavite from 'vavite'
```
correct
```
import { vavite } from 'vavite'
```
v3.0.0 changed from default export to named export. Using default import will result in a runtime error.
VavitePluginOptions
wrong
```
import { VavitePluginOptions } from 'vavite'
```
correct
```
import type { VavitePluginOptions } from 'vavite'
```
VavitePluginOptions is a TypeScript type, not a value; it should be imported with the `type` keyword (or use `import type`).
defineConfig
wrong
```
import { defineConfig } from 'vavite'
```
correct
```
import { defineConfig } from 'vite'
```
defineConfig is from Vite, not from vavite. A common mistake is confusing the source.

Quickstart

Minimal project setup: Vite config with vavite plugin, and a handler entry that responds to root requests with HTML and starts a standalone production server.

// vite.config.ts
import { defineConfig } from 'vite';
import { vavite } from 'vavite';

export default defineConfig({
  appType: 'custom',
  plugins: [
    vavite({
      // Optional: entries, type, etc.
    }),
  ],
});

// src/entry.server.ts
/// <reference types="vite/client" />
/// <reference types="vavite/types" />

import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';

export default function handler(req: IncomingMessage, res: ServerResponse) {
  if (req.url === '/') {
    res.setHeader('Content-Type', 'text/html; charset=utf-8').end('<h1>Hello from vavite!</h1>');
  } else {
    res.statusCode = 404;
    res.end('Not found');
  }
}

if (import.meta.env.COMMAND === 'build') {
  createServer(handler).listen(3000, () => console.log('Server on http://localhost:3000'));
}

if (import.meta.hot) {
  import.meta.hot.accept();
}