Vite Plugin for srvx

1.0.2 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.0.2) that integrates srvx (Universal Server) with Vite's development server, enabling HMR and automatic index.html serving for srvx-based projects. It supports Node.js, Deno, Bun, and Vercel Edge Functions. Similar to @hono/vite-dev-server but for srvx. Monthly releases with TypeScript types. Key differentiator: srvx's universal runtime and built-in static file serving.

Common errors

error Error: The plugin returned an array, but Vite expects a single plugin. ↓

cause Using srvx({...}) without spread operator in plugins array.

fix

Use ...srvx({...}) instead.

error Error: [vite] Internal server error: Failed to load module /src/server.ts ↓

cause Entry file path mismatch or missing entry file.

fix

Check entry option in srvx() and ensure server file exists.

error Error: Cannot find module 'srvx' ↓

cause Missing srvx peer dependency.

fix

Run npm install srvx

Warnings

breaking The plugin returns an array of Vite plugins (using spread), not a single plugin. ↓

fix Use ...srvx({...}) in the plugins array, not just srvx({...}).

gotcha For production, you must run two separate Vite builds: one for client and one for server (with --mode server). ↓

fix Add scripts: "build": "vite build && vite build --mode server"

gotcha The plugin expects the entry file to export a default object with a 'fetch' method (Request => Response). Non-standard exports will break. ↓

fix Ensure export default { async fetch(request: Request): Promise<Response> { ... } }

gotcha When using Vercel deployment, the plugin auto-detects VERCEL=1 env var and changes output path to dist/api/index.js. This may conflict with other configurations. ↓

fix Set framework option explicitly or unset VERCEL env var if not deploying to Vercel.

Install

npm install vite-plugin-srvx

yarn add vite-plugin-srvx

pnpm add vite-plugin-srvx

Imports

default
wrong
```
const srvx = require('vite-plugin-srvx')
```
correct
```
import srvx from 'vite-plugin-srvx'
```
Default import; CommonJS require may not work in ESM-only environments but plugin is primarily used in Vite config files which support both.

SrvxOptions

import type { SrvxOptions } from 'vite-plugin-srvx'

TypeScript type import for options object.

loadModule

wrong

import loadModule from 'vite-plugin-srvx'

correct

import { loadModule } from 'vite-plugin-srvx'

Named export for custom loadModule option; not a default export.

defineConfig

wrong

import { defineConfig } from 'vite-plugin-srvx'

correct

import { defineConfig } from 'vite'

defineConfig is from Vite, not from this plugin.

Quickstart

Basic setup: Vite config, srvx server file, and index.html for dev with HMR.

// vite.config.ts
import { defineConfig } from 'vite'
import srvx from 'vite-plugin-srvx'

export default defineConfig({
  plugins: [
    ...srvx({
      entry: './src/server.ts',
    }),
  ],
})

// src/server.ts
export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url)
    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Hello from srvx!', timestamp: new Date().toISOString() })
    }
    return new Response('Not Found', { status: 404 })
  },
}

// index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My srvx App</title>
</head>
<body>
  <h1>Hello from srvx + Vite!</h1>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>