Skip to main content

​
Prerequisites

Elysia runs on Bun, a fast all-in-one JavaScript runtime. Before installing Elysia, you’ll need to install Bun.

​
System requirements

  • macOS, Linux, or Windows (via WSL)
  • Node.js is not required - Bun is a complete runtime

​
Install Bun

curl -fsSL https://bun.sh/install | bash
After installation, verify Bun is working: 
bun --version
Bun includes a package manager, test runner, bundler, and runtime - everything you need to build with Elysia.

​
Create a new project

1

Use the Elysia scaffolding tool

The fastest way to get started is with the official scaffolding tool:
bun create elysia app
This creates a new directory called app with a basic Elysia project structure.
2

Navigate to your project

cd app
3

Install dependencies

Dependencies are automatically installed by bun create, but you can reinstall them if needed:
bun install
4

Start the development server

bun dev
Your Elysia server is now running at http://localhost:3000!

​
Manual installation

If you prefer to set up your project manually:
1

Create a new directory

mkdir my-elysia-app
cd my-elysia-app
2

Initialize a new project

bun init -y
This creates a package.json file and basic project structure.
3

Install Elysia

bun add elysia
4

Create your first server

Create a file named index.ts:
index.ts
import { Elysia } from 'elysia'

const app = new Elysia()
  .get('/', () => 'Hello Elysia')
  .listen(3000)

console.log(
  `🦊 Elysia is running at http://${app.server?.hostname}:${app.server?.port}`
)
5

Run your server

bun run index.ts
Visit http://localhost:3000 to see your app in action!

​
Project structure

A typical Elysia project structure looks like this: 
my-elysia-app/
├── src/
│   └── index.ts       # Main application file
├── package.json       # Project dependencies
├── tsconfig.json      # TypeScript configuration
└── README.md
Elysia doesn’t enforce a specific project structure. Organize your code however works best for your project.

​
Development setup

​
TypeScript configuration

Elysia works best with TypeScript. Here’s a recommended tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "types": ["bun-types"]
  }
}

​
Hot reload during development

Bun supports hot reloading out of the box: 
bun --watch src/index.ts
Your server will automatically restart when you save changes.

​
Installing plugins

Elysia has a rich ecosystem of official and community plugins. Install them with Bun: 
# OpenAPI documentation
bun add @elysiajs/swagger

# CORS support
bun add @elysiajs/cors

# JWT authentication
bun add @elysiajs/jwt

# Static file serving
bun add @elysiajs/static
Example usage: 
import { Elysia } from 'elysia'
import { swagger } from '@elysiajs/swagger'
import { cors } from '@elysiajs/cors'

const app = new Elysia()
  .use(swagger())
  .use(cors())
  .get('/', () => 'Hello Elysia')
  .listen(3000)

​
Runtime adapters

While Elysia is optimized for Bun, it also supports other runtimes through adapters:

Bun (default)

Native support with optimal performance.

Cloudflare Workers

Deploy to edge with the Cloudflare Workers adapter.

Web Standard

Use the web standard adapter for maximum compatibility.

Node.js

Limited support via web standard adapter (Bun recommended).
For the best experience and performance, use Bun as your runtime. Other adapters may have limitations.

​
Verify installation

To verify everything is working correctly, create a simple test:
test.ts
import { Elysia } from 'elysia'

const app = new Elysia()
  .get('/health', () => ({ status: 'ok', timestamp: Date.now() }))
  .listen(3000)

console.log('Server running at http://localhost:3000/health')
Run it with: 
bun run test.ts
Visit http://localhost:3000/health - you should see a JSON response.

​
Next steps

Quick start guide

Build your first real application with Elysia.

Core concepts

Learn about routing, handlers, and context.

Validation

Add schema validation to your routes.

Plugins

Extend Elysia with plugins.

Build docs developers (and LLMs) love

Get started for freeTalk to us