Vite Integration

Lucent provides a Vite plugin for full-stack development, allowing you to run Lucent's Elysia API inside the Vite dev server.

Installation

The Vite integration is included with @codesordinatestudio/lucent:

bun add @codesordinatestudio/lucent vite

Configuration

Add lucent.vite() to your vite.config.ts:

import { defineConfig } from "vite";
import { lucent } from "@codesordinatestudio/lucent";

export default defineConfig({
  plugins: [
    lucent.vite({
      serverFile: "/server/api.ts",
      apiPrefix: "/api",
      maxBodySize: 1048576, // 1MB
      wsPath: "/ws", // WebSocket endpoint (default: "/ws")
      wsPort: 3001, // Internal WS proxy port (default: 3001)
    }),
  ],
});

Options

Option	Type	Default	Description
serverFile	string	"/server/api.ts"	Path to your API module
apiPrefix	string	"/api"	URL prefix for API routes
maxBodySize	number	1048576	Max request body size in bytes
wsPath	string | false	"/ws"	WebSocket path. Upgrade requests are proxied to an internal Bun WS server. Set to false to disable.
wsPort	number	3001	Internal port for the Bun WebSocket proxy server (dev only)

Project Structure

my-project/
├── server/
│   └── api.ts          # Elysia API entry
├── src/
│   ├── components/
│   └── pages/
├── vite.config.ts
└── lucent.config.ts

Server Entry

Create your API entry file:

// server/api.ts
import { Elysia } from "elysia";
import { lucent } from "../lucent.config";

export default new Elysia().use(lucent).listen(3000);

Development

Start the dev server:

vite

Now:

• Frontend: http://localhost:5173
• API: http://localhost:5173/api

API requests matching apiPrefix are forwarded to Elysia; everything else goes through Vite.

Hot Reload

Changes to your API module automatically reload the Lucent server. The plugin watches:

• The main API entry file
• All dependencies in the API module graph

Production Build

Use the Lucent CLI to build for production — no separate build script file needed.

You can also call the builder directly:

import { lucent } from "@codesordinatestudio/lucent";

await lucent.vite.build({ entry: "server/api.ts" });

Add these scripts to your package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "lucent vite build",
    "start": "bun build/server.js"
  }
}

Then run:

bun run build
bun run start

API-only Build

Bundles just the Elysia API into build/server.js:

lucent vite build
# or with a custom entry
lucent vite build src/server/api.ts

Full-stack Build

Runs vite build first, then bundles the API and static frontend into a single server:

lucent vite build --fullstack

Output:

• build/server.js — Bun server that handles both API and static files
• build/public/ — copied from your Vite dist/

Start with: bun build/server.js

CLI Flags

Flag	Default	Description
[entry]	"server/api.ts"	Path to the API entry file (positional)
--out-dir	"build"	Output directory
--fullstack	false	Run vite build + bundle API into single server
--api-prefix	"/api"	URL prefix for API routes in static server
--vite-dist	"dist"	Vite frontend output directory
--no-minify	—	Disable minification

Build Options

Option	Type	Default	Description
entry	string	"server/api.ts"	API entry file
outDir	string	"build"	Output directory
target	"bun"	"bun"	Build target
minify	boolean	true	Minify output
fullstack	boolean	false	Combined frontend+API build
viteDist	string	"dist"	Vite output directory
apiPrefix	string	"/api"	API prefix in static server