vite-elysia-forge

A Vite middleware plugin that hot-reloads an Elysia API module and forwards /api requests to it during local development. Powered by Bun.

1. Installation

``bash
bun install vite-elysia-forge
`

2. Quick Start

$3

Place your Elysia handler at server/api.ts (default path):

`ts
import { Elysia } from "elysia";

export const api = new Elysia({
prefix: "/api",
});

api.get("/", () => "hello from elysia");

export default api;
`

$3

Register the plugin in your Vite config:

`ts
import { defineConfig } from "vite";
import elysiaPlugin from "vite-elysia-forge";

export default defineConfig({
plugins: [
elysiaPlugin({
serverFile: "./server/api.ts",
}),
],
});
`

$3

Run Vite as usual and access your API at /api/* routes. The plugin will automatically reload the Elysia module when files change.

`bash
bun run dev
`

3. Configuration Options

$3

You 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. |

`ts
elysiaPlugin({
serverFile: "/server/api.ts",
ws: true,
apiPrefix: "/api",
backendPort: 3001,
MAX_BODY_SIZE: 1024 * 1024, // 1MB
});
`

4. API Module Requirements

Your API module must export an Elysia instance as api.

$3

`ts
import { Elysia } from "elysia";

export const api = new Elysia({
prefix: "/api",
});

api.get("/", () => "hello from elysia");
api.get("/users", () => ["user1", "user2"]);

export default api;
`

$3

`ts
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;
`

5. WebSocket Support

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:

`ts
elysiaPlugin({
serverFile: "./server/api.ts",
ws: true, // Enable WebSocket support
backendPort: 3001, // API runs on this port (default: 3001)
});
`

$3

When ws: true:

1. The plugin spawns a separate Bun process that runs your API with api.listen(backendPort).
2. Vite is configured to proxy /api requests (including WebSocket upgrades) to that backend.
3. 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.

$3

In production, the built server (build/server.js or the compiled binary) runs your Elysia app directly with full WebSocket support—no proxy needed.

6. Integration with @elysiajs/openapi

To use the @elysiajs/openapi plugin, add the following to your tsconfig.json:

`json
{
"compilerOptions": {
"types": ["bun-types"],
"typeRoots": ["node_modules"]
}
}
`

$3

It is recommended to pre-generate the declaration file (.d.ts) to provide type declaration to the generator.

`ts
import { Elysia, t } from "elysia";
import { openapi, fromTypes } from "@elysiajs/openapi";

const app = new Elysia().use(
openapi({
references: fromTypes("server/api"),
})
);
`

7. Production Deployment

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.

$3

Build your frontend using Vite directly:

`bash
vite build
`

Output:

`
dist/
├── index.html
└── assets/
`

Deploy to any static host (Cloudflare Pages, Netlify, Vercel, etc.)

$3

Build the Elysia API server into a standalone JavaScript bundle.

`bash
vite-elysia-forge build --outDir dist
`

What it does:

1. Generates a production entry file that imports your API
2. Bundles the server into dist/server.js

package.json:

`json
{
"scripts": {
"build:server": "vite-elysia-forge build --outDir dist",
"start": "bun dist/server.js"
}
}
`

With custom entry and target:

`bash
vite-elysia-forge build --entry src/my-api.ts --outDir .output --target node
`

$3

Build and compile the server into a standalone executable (no Bun runtime required).

`bash
vite-elysia-forge build --outFile server
`

What it does:

1. Bundles the server code
2. Compiles into a native binary at the specified path

package.json:

`json
{
"scripts": {
"build:server": "vite-elysia-forge build --outFile dist/server",
"start": "./dist/server"
}
}
`

$3

Command:

`bash
vite-elysia-forge build [options]
`

Options:

| Option | Short | Default | Description |
| :------------------ | :---: | :-------------- | :----------------------------------------- |
| --entry | -e | server/api.ts | Path to API entry file |
| --outDir