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

bun install vite-elysia-forge

2. Quick Start

2.1 Create Your API Handler

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

import { Elysia } from "elysia";

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

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

export default api;

2.2 Configure Vite

Register the plugin in your Vite config:

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

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

2.3 Start Development

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

bun run dev

3. Configuration Options

3.1 Plugin Options

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

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.

4.1 Basic Example

import { Elysia } from "elysia";

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

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

export default api;

4.2 WebSocket Example

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:

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

5.1 How WS Mode Works

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.

5.2 Production

In production, the built server (dist/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:

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

6.1 Example with fromTypes

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"),
  })
);

7. Production Deployment

7.1 Build Configuration

Update your package.json scripts:

Pick one build mode.

Option A: build to dist/server.js (run with Bun):

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

Option B: build + compile to a standalone binary dist/server:

{
  "scripts": {
    "dev": "vite",
    "build": "vite-elysia-forge build-compile",
    "start": "./dist/server"
  }
}

If your API is located elsewhere, specify the path:

vite-elysia-forge build src/my-api.ts

7.2 Building for Production

Run the build command:

bun run build

This command performs the following steps:

1. Runs vite build to compile your frontend to dist/
2. Automatically generates a temporary entry file that imports your API from src/server/api.ts
3. Bundles the server into a single file at dist/server.js

7.3 Building a Standalone Binary

If you want a single executable (no Bun runtime required on the target machine), set your build script to vite-elysia-forge build-compile (Option B above) and run:

bun run build

This runs the normal build and then compiles dist/server.js into a standalone binary at dist/server.

7.4 Starting the Production Server

Start the server with:

bun start

8. Troubleshooting

8.1 "Bun is not defined" Error

If you encounter this error, ensure you are running Vite with the Bun runtime:

bunx --bun vite

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

8.2 Hot Reload Not Working

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.

8.3 WebSocket "adapter doesn't support" Error

If you see Current adapter doesn't support WebSocket, you need to enable WS mode:

elysiaPlugin({
  serverFile: "./src/server/api.ts",
  ws: true,
});

This spawns your API as a separate Bun process with full WebSocket support.

8.4 "ReferenceError: process is not defined" with OpenAPI

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') ```

9. Authors

• Chijioke Udokporo (@chijiokeudokporo)

10. License

MIT