A Vite middleware plugin that hot-reloads an Elysia API module and forwards /api requests to it during local development. Powered by Bun.
bun install vite-elysia-forgePlace your Elysia handler at server/api.ts (default path):
import { Elysia } from "elysia";
export const api = new Elysia({
prefix: "/api",
});
api.get("/", () => "hello from elysia");
export default api;Register the plugin in your Vite config:
import { defineConfig } from "vite";
import elysiaPlugin from "vite-elysia-forge";
export default defineConfig({
plugins: [
elysiaPlugin({
serverFile: "./server/api.ts",
}),
],
});Run Vite as usual and access your API at /api/* routes. The plugin will automatically reload the Elysia module when files change.
bun run devYou can configure the plugin by passing an object with the following options:
| Option Key | Required | Default | Description |
|---|---|---|---|
serverFile |
No | "/server/api.ts" |
Path to your Elysia API module (relative to project root). |
ws |
No | false |
Enable WebSocket support. Runs API as a separate process + Vite proxy. |
apiPrefix |
No | "/api" |
Path prefix for API routes. Used for proxying in ws mode. |
backendPort |
No | 3001 |
Port for the backend API server in ws mode. |
MAX_BODY_SIZE |
No | 1048576 (1MB) |
Maximum allowed size for request bodies in bytes. |
elysiaPlugin({
serverFile: "/server/api.ts",
ws: true,
apiPrefix: "/api",
backendPort: 3001,
MAX_BODY_SIZE: 1024 * 1024, // 1MB
});Your API module must export an Elysia instance as api.
import { Elysia } from "elysia";
export const api = new Elysia({
prefix: "/api",
});
api.get("/", () => "hello from elysia");
api.get("/users", () => ["user1", "user2"]);
export default api;import { Elysia } from "elysia";
export const api = new Elysia({
prefix: "/api",
})
.get("/", () => "hello from elysia")
.ws("/ws", {
message(ws, message) {
ws.send(`Echo: ${message}`);
},
});
export default api;By default, the plugin runs your API as middleware inside Vite's dev server. This works great for HTTP routes but does not support WebSockets (Elysia's .ws() routes).
To enable WebSocket support, set ws: true:
elysiaPlugin({
serverFile: "./server/api.ts",
ws: true, // Enable WebSocket support
backendPort: 3001, // API runs on this port (default: 3001)
});When ws: true:
- The plugin spawns a separate Bun process that runs your API with
api.listen(backendPort). - Vite is configured to proxy
/apirequests (including WebSocket upgrades) to that backend. - On file changes, the backend process is automatically restarted.
This ensures full Bun runtime support for WebSockets, even if Vite itself runs under Node.js.
In production, the built server (build/server.js or the compiled binary) runs your Elysia app directly with full WebSocket support—no proxy needed.
To use the @elysiajs/openapi plugin, add the following to your tsconfig.json:
{
"compilerOptions": {
"types": ["bun-types"],
"typeRoots": ["node_modules"]
}
}It is recommended to pre-generate the declaration file (.d.ts) to provide type declaration to the generator.
import { Elysia, t } from "elysia";
import { openapi, fromTypes } from "@elysiajs/openapi";
const app = new Elysia().use(
openapi({
references: fromTypes("server/api"),
}),
);The CLI provides a build command for building your Elysia API server. Frontend assets should be built separately using Vite's standard build process (vite build).
By default, the CLI looks for your API at server/api.ts. You can specify a custom path with the --entry flag.
Build your frontend using Vite directly:
vite buildOutput:
dist/
├── index.html
└── assets/
Deploy to any static host (Cloudflare Pages, Netlify, Vercel, etc.)
Build the Elysia API server into a standalone JavaScript bundle.
vite-elysia-forge build --outDir distWhat it does:
- Generates a production entry file that imports your API
- Bundles the server into
dist/server.js
package.json:
{
"scripts": {
"build:server": "vite-elysia-forge build --outDir dist",
"start": "bun dist/server.js"
}
}With custom entry and target:
vite-elysia-forge build --entry src/my-api.ts --outDir .output --target nodeBuild and compile the server into a standalone executable (no Bun runtime required).
vite-elysia-forge build --outFile serverWhat it does:
- Bundles the server code
- Compiles into a native binary at the specified path
package.json:
{
"scripts": {
"build:server": "vite-elysia-forge build --outFile dist/server",
"start": "./dist/server"
}
}Command:
vite-elysia-forge build [options]Options:
| Option | Short | Default | Description |
|---|---|---|---|
--entry <path> |
-e |
server/api.ts |
Path to API entry file |
--outDir <dir> |
-d |
dist |
Output directory for bundled server.js |
--outFile <file> |
-o |
— | Output path for compiled standalone binary |
--target <target> |
-t |
bun |
Build target: bun, node, or browser |
--no-minify |
— | — | Disable minification |
Note:
--outDirand--outFileare mutually exclusive. Use--outDirfor a bundled JS file, or--outFilefor a compiled binary.
Examples:
# Bundle server to dist/server.js
vite-elysia-forge build --outDir dist
# Bundle with node target
vite-elysia-forge build --outDir build--target node
# Compile to standalone binary
vite-elysia-forge build --outFile server
# Compile with custom entry
vite-elysia-forge build --entry src/api/index.ts --outFile myserver
# Bundle without minification
vite-elysia-forge build --outDir build--no-minifySeparate deployment (recommended):
┌─────────────────┐ ┌──────────────────┐
│ Static Host │ │ API Server │
│ (CDN/Pages) │◄────────┤ (VPS/Cloud) │
│ │ CORS │ │
│ dist/ │ │ dist/server.js │
└─────────────────┘ └──────────────────┘
- Frontend: Build with
vite buildand deploy to Cloudflare Pages, Netlify, Vercel, etc. - Backend: Build with
vite-elysia-forge build --outDir distand deploy to any server with Bun installed, or use the compiled binary
API-only deployment:
If you have no frontend, just build and deploy the server:
vite-elysia-forge build --outDir dist
bun dist/server.jsIf you encounter this error, ensure you are running Vite with the Bun runtime:
bunx --bun viteOr update your dev script in package.json:
"scripts": {
"dev": "bunx --bun vite"
}Benefits:
- Access to Bun APIs: You can use
Bun.file,Bun.env,bun:sqlite, and other native Bun features directly in your server code. - Performance: Vite often starts faster and uses less memory when running under Bun.
Caveats:
- Node.js Compatibility: While Bun has excellent Node.js compatibility, some Vite plugins that rely on obscure Node.js internals might behave unexpectedly.
- Performance: Running Vite under Bun is generally faster, but you might encounter edge cases where optimization differs from Node.js.
Check that your file changes are within the dependency graph of your API module. The plugin uses Vite's dependency tracking to determine when to reload.
If you see Current adapter doesn't support WebSocket, you need to enable WS mode:
elysiaPlugin({
serverFile: "./server/api.ts",
ws: true,
});This spawns your API as a separate Bun process with full WebSocket support.
If you use @elysiajs/openapi with fromTypes and see this error in the browser console:
``` Uncaught ReferenceError: process is not defined at fromTypes ... ```
This happens because `fromTypes` relies on Node.js/Bun APIs that don't exist in the browser. It usually means you are importing your server file as a value in client-side code.
Solution: Use `import type` when importing your API instance for Eden Treaty.
```ts // ❌ Incorrect import { api } from './server/api' const client = treaty(api)
// ✅ Correct import type { api } from './server/api' const client = treaty('localhost:3000') ```
- Chijioke Udokporo (@chijiokeudokporo)
MIT