elysiajs

Name: elysiajs
Author: elysiajs

elysiatypescriptbunbackendweb frameworkapi developmentperformancetype-safety

⭐ 65🕒 2026-01-20Source ↗

Install this skill

npx skills add elysiajs/skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

ElysiaJS is a web framework built for the Bun runtime, prioritizing type safety and developer ergonomics through a chainable, fluent API. It performs static analysis on routes to generate highly optimized code, resulting in rapid execution speeds. By tightly integrating with TypeBox, the framework enforces schema validation at both the input (body, query, headers) and output levels, ensuring internal consistency across the entire request lifecycle. It supports a modular architecture via plugins and standardizes common backend concerns such as CORS, authentication, and state management without the configuration overhead common in traditional Node.js frameworks. The syntax is designed for TypeScript developers who prefer explicit type declarations and minimal boilerplate when defining complex API structures or microservices.

When to Use This Skill

•Developing high-performance microservices requiring strict data validation
•Building full-stack type-safe APIs shared with frontend consumers via Eden Treaty
•Creating lightweight serverless functions or containerized backend services
•Managing real-time applications using built-in WebSocket handlers

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“Create an ElysiaJS server with route validation
“How to handle file uploads in an Elysia application
“Set up JWT authentication guards in Elysia
“Generate types for my Elysia API for the frontend
“Define a Zod schema for an Elysia POST request

Pro Tips

💡Always consult `elysiajs.com/llms.txt` for the most current API details and examples, as the framework is actively developed.
💡Utilize Elysia's robust plugin system and macros to modularize common functionalities like CORS, JWT handling, or custom request decorators.
💡Leverage Bun's native features and the type-safety of ElysiaJS to write highly performant and maintainable backend code.

What this skill does

•Automatic type inference and schema validation for request payloads and response bodies
•Fluent API design for defining HTTP handlers, path parameters, and headers
•Built-in support for TypeBox, Zod, and Valibot schema definitions
•Modular architecture utilizing plugins, guards, and macros for reusable logic
•First-class support for WebSockets and streaming responses
•Optimized request handling tailored for the Bun runtime

When not to use it

✕Applications requiring a legacy Node.js environment without access to Bun
✕Projects needing an enterprise framework with built-in ORM/migrations like NestJS
✕Systems heavily reliant on libraries with complex native C++ Node.js bindings

Example workflow

Initialize a new project using bun create elysia
Define business logic and TypeBox models within a module directory
Assemble the application using a primary Elysia instance with specific plugins
Attach authentication guards to protected routes
Implement route handlers using destructured request parameters
Expose the Eden Treaty client for frontend type sharing

Prerequisites

–Bun runtime installed on the machine
–Basic proficiency in TypeScript
–Understanding of schema-based validation concepts

Pitfalls & limitations

!Strict type requirements can lead to verbose boilerplate for complex objects
!Framework performance is tightly coupled to Bun; behavior may differ if deployed elsewhere
!The plugin system differs significantly from standard Express middleware patterns

FAQ

Can I use Zod instead of TypeBox?

Yes, Elysia supports Zod, Valibot, and ArkType natively, allowing you to validate request bodies and parameters using your preferred schema library.

Does Elysia work on Node.js?

Elysia is primarily designed for Bun, but it can run on Node.js using adapters, though it is highly optimized for the Bun runtime environment.

How do I share types between backend and frontend?

You can use Eden Treaty, which allows you to import the app instance type from your backend and provides full type-safe client methods for your frontend.

How it compares

Unlike manual request parsing in Express, Elysia enforces types and validates schemas at the declaration level, preventing runtime type errors through static analysis.

Source & trust

⭐ 65 stars🕒 Updated 2026-01-20

View original skill on GitHub →

📄 Full skill instructions — original source: elysiajs/skills

# ElysiaJS Development Skill

Always consult [elysiajs.com/llms.txt](https://elysiajs.com/llms.txt) for code examples and latest API.

## Overview

ElysiaJS is a TypeScript framework for building Bun-first (but not limited to Bun) type-safe, high-performance backend servers. This skill provides comprehensive guidance for developing with Elysia, including routing, validation, authentication, plugins, integrations, and deployment.

## When to Use This Skill

Trigger this skill when the user asks to:
- Create or modify ElysiaJS routes, handlers, or servers
- Setup validation with TypeBox or other schema libraries (Zod, Valibot)
- Implement authentication (JWT, session-based, macros, guards)
- Add plugins (CORS, OpenAPI, Static files, JWT)
- Integrate with external services (Drizzle ORM, Better Auth, Next.js, Eden Treaty)
- Setup WebSocket endpoints for real-time features
- Create unit tests for Elysia instances
- Deploy Elysia servers to production

## Quick Start
Quick scaffold:

bun create elysia app

### Basic Server

import { Elysia, t, status } from 'elysia'

const app = new Elysia()
  	.get('/', () => 'Hello World')
   	.post('/user', ({ body }) => body, {
    	body: t.Object({
      		name: t.String(),
        	age: t.Number()
     	})
    })
    .get('/id/:id', ({ params: { id } }) => {
   		if(id > 1_000_000) return status(404, 'Not Found')
     
     	return id
    }, {
    	params: t.Object({
     		id: t.Number({
       			minimum: 1
       		})
     	}),
     	response: {
      		200: t.Number(),
        	404: t.Literal('Not Found')
      	}
    })
    .listen(3000)

## Basic Usage

### HTTP Methods

import { Elysia } from 'elysia'

new Elysia()
  .get('/', 'GET')
  .post('/', 'POST')
  .put('/', 'PUT')
  .patch('/', 'PATCH')
  .delete('/', 'DELETE')
  .options('/', 'OPTIONS')
  .head('/', 'HEAD')

### Path Parameters

.get('/user/:id', ({ params: { id } }) => id)
.get('/post/:id/:slug', ({ params }) => params)

### Query Parameters

.get('/search', ({ query }) => query.q)
// GET /search?q=elysia → "elysia"

### Request Body

.post('/user', ({ body }) => body)

### Headers

.get('/', ({ headers }) => headers.authorization)

## TypeBox Validation

### Basic Types

import { Elysia, t } from 'elysia'

.post('/user', ({ body }) => body, {
  body: t.Object({
    name: t.String(),
    age: t.Number(),
    email: t.String({ format: 'email' }),
    website: t.Optional(t.String({ format: 'uri' }))
  })
})

### Nested Objects

body: t.Object({
  user: t.Object({
    name: t.String(),
    address: t.Object({
      street: t.String(),
      city: t.String()
    })
  })
})

### Arrays

body: t.Object({
  tags: t.Array(t.String()),
  users: t.Array(t.Object({
    id: t.String(),
    name: t.String()
  }))
})

### File Upload

.post('/upload', ({ body }) => body.file, {
  body: t.Object({
    file: t.File({
      type: 'image',              // image/* mime types
      maxSize: '5m'               // 5 megabytes
    }),
    files: t.Files({              // Multiple files
      type: ['image/png', 'image/jpeg']
    })
  })
})

### Response Validation

.get('/user/:id', ({ params: { id } }) => ({
  id,
  name: 'John',
  email: '[email protected]'
}), {
  params: t.Object({
    id: t.Number()
  }),
  response: {
    200: t.Object({
      id: t.Number(),
      name: t.String(),
      email: t.String()
    }),
    404: t.String()
  }
})

## Standard Schema (Zod, Valibot, ArkType)

### Zod

import { z } from 'zod'

.post('/user', ({ body }) => body, {
  body: z.object({
    name: z.string(),
    age: z.number().min(0),
    email: z.string().email()
  })
})

## Error Handling

.get('/user/:id', ({ params: { id }, status }) => {
  const user = findUser(id)
  
  if (!user) {
    return status(404, 'User not found')
  }
  
  return user
})

## Guards (Apply to Multiple Routes)

.guard({
  params: t.Object({
    id: t.Number()
  })
}, app => app
  .get('/user/:id', ({ params: { id } }) => id)
  .delete('/user/:id', ({ params: { id } }) => id)
)

## Macro

.macro({
  hi: (word: string) => ({
    beforeHandle() { console.log(word) }
  })
})
.get('/', () => 'hi', { hi: 'Elysia' })

### Project Structure (Recommended)
Elysia takes an unopinionated approach but based on user request. But without any specific preference, we recommend a feature-based and domain driven folder structure where each feature has its own folder containing controllers, services, and models.

src/
├── index.ts              # Main server entry
├── modules/
│   ├── auth/
│   │   ├── index.ts      # Auth routes (Elysia instance)
│   │   ├── service.ts    # Business logic
│   │   └── model.ts      # TypeBox schemas/DTOs
│   └── user/
│       ├── index.ts
│       ├── service.ts
│       └── model.ts
└── plugins/
    └── custom.ts

public/                   # Static files (if using static plugin)
test/                     # Unit tests

Each file has its own responsibility as follows:
- **Controller (index.ts)**: Handle HTTP routing, request validation, and cookie.
- **Service (service.ts)**: Handle business logic, decoupled from Elysia controller if possible.
- **Model (model.ts)**: Define the data structure and validation for the request and response.

## Best Practice
Elysia is unopinionated on design pattern, but if not provided, we can relies on MVC pattern pair with feature based folder structure.

- Controller:
- Prefers Elysia as a controller for HTTP dependant controller
- For non HTTP dependent, prefers service instead unless explicitly asked
- Use onError to handle local custom errors
- Register Model to Elysia instance via Elysia.models({ ...models }) and prefix model by namespace

Elysia.prefix('model', 'Namespace.')
	- Prefers Reference Model by name provided by Elysia instead of using an actual

Model.name


- Service:
	- Prefers class (or abstract class if possible)
	- Prefers interface/type derive from

Model


	- Return

status (import { status } from 'elysia'

) for error
	- Prefers

return Error instead of throw Error


- Models:
	- Always export validation model and type of validation model
	- Custom Error should be in contains in Model

## Elysia Key Concept
Elysia has a every important concepts/rules to understand before use.

## Encapsulation - Isolates by Default

Lifecycles (hooks, middleware) **don't leak** between instances unless scoped.

**Scope levels:**
-

local

 (default) - current instance + descendants
-

scoped

 - parent + current + descendants  
-

global

 - all instances

.onBeforeHandle(() => {}) // only local instance
.onBeforeHandle({ as: 'global' }, () => {}) // exports to all


## Method Chaining - Required for Types

**Must chain**. Each method returns new type reference.

❌ Don't:
const app = new Elysia()
app.state('build', 1) // loses type
app.get('/', ({ store }) => store.build) // build doesn't exists


✅ Do:
new Elysia()
  .state('build', 1)
  .get('/', ({ store }) => store.build)


## Explicit Dependencies

Each instance independent. **Declare what you use.**

const auth = new Elysia()
	.decorate('Auth', Auth)
	.model(Auth.models)

new Elysia()
  .get('/', ({ Auth }) => Auth.getProfile()) // Auth doesn't exists

new Elysia()
  .use(auth) // must declare
  .get('/', ({ Auth }) => Auth.getProfile())


**Global scope when:**
- No types added (cors, helmet)
- Global lifecycle (logging, tracing)

**Explicit when:**
- Adds types (state, models)
- Business logic (auth, db)

## Deduplication

Plugins re-execute unless named:

new Elysia() // rerun on .use
new Elysia({ name: 'ip' }) // runs once across all instances


## Order Matters

Events apply to routes **registered after** them.

.onBeforeHandle(() => console.log('1'))
.get('/', () => 'hi') // has hook
.onBeforeHandle(() => console.log('2')) // doesn't affect '/'


## Type Inference

**Inline functions only** for accurate types.

For controllers, destructure in inline wrapper:

.post('/', ({ body }) => Controller.greet(body), {
  body: t.Object({ name: t.String() })
})


Get type from schema:
type MyType = typeof MyType.static


## Reference Model
Model can be reference by name, especially great for documenting an API
new Elysia()
	.model({
		book: t.Object({
			name: t.String()
		})
	})
	.post('/', ({ body }) => body.name, {
		body: 'book'
	})


Model can be renamed by using

.prefix / .suffix


new Elysia()
	.model({
		book: t.Object({
			name: t.String()
		})
	})
	.prefix('model', 'Namespace')
	.post('/', ({ body }) => body.name, {
		body: 'Namespace.Book'
	})


Once

prefix

, model name will be capitalized by default.

## Technical Terms
The following are technical terms that is use for Elysia:
-

OpenAPI Type Gen - function name fromTypes from @elysiajs/openapi for generating OpenAPI from types, see plugins/openapi.md

Eden, Eden Treaty

 - e2e type safe RPC client for share type from backend to frontend

## Resources
Use the following references as needed.

It's recommended to checkout

route.md

 for as it contains the most important foundation building blocks with examples.

plugin.md and validation.md

 is important as well but can be check as needed.

### references/
Detailed documentation split by topic:
-

bun-fullstack-dev-server.md

 - Bun Fullstack Dev Server with HMR. React without bundler.
-

cookie.md

 - Detailed documentation on cookie
-

deployment.md

 - Production deployment guide / Docker
-

eden.md

 - e2e type safe RPC client for share type from backend to frontend
-

guard.md

 - Setting validation/lifecycle all at once
-

macro.md

 - Compose multiple schema/lifecycle as a reusable Elysia via key-value (recommended for complex setup, eg. authentication, authorization, Role-based Access Check)
-

plugin.md

 - Decouple part of Elysia into a standalone component
-

route.md

 - Elysia foundation building block: Routing, Handler and Context
-

testing.md

 - Unit tests with examples
-

validation.md

 - Setup input/output validation and list of all custom validation rules
-

websocket.md

 - Real-time features

### plugins/ 
Detailed documentation, usage and configuration reference for official Elysia plugin:
-

bearer.md - Add bearer capability to Elysia (@elysiajs/bearer

)
-

cors.md - Out of box configuration for CORS (@elysiajs/cors

)
-

cron.md - Run cron job with access to Elysia context (@elysiajs/cron

)
-

graphql-apollo.md - Integration GraphQL Apollo (@elysiajs/graphql-apollo

)
-

graphql-yoga.md - Integration with GraphQL Yoga (@elysiajs/graphql-yoga

)
-

html.md - HTML and JSX plugin setup and usage (@elysiajs/html

)
-

jwt.md - JWT / JWK plugin (@elysiajs/jwt

)
-

openapi.md - OpenAPI documentation and OpenAPI Type Gen / OpenAPI from types (@elysiajs/openapi

)
-

opentelemetry.md - OpenTelemetry, instrumentation, and record span utilities (@elysiajs/opentelemetry

)
-

server-timing.md - Server Timing metric for debug (@elysiajs/server-timing

) 
-

static.md - Serve static files/folders for Elysia Server (@elysiajs/static

)

### integrations/
Guide to integrate Elysia with external library/runtime:
-

ai-sdk.md

 - Using Vercel AI SDK with Elysia
-

astro.md

 - Elysia in Astro API route
-

better-auth.md

 - Integrate Elysia with better-auth
-

cloudflare-worker.md

 - Elysia on Cloudflare Worker adapter
-

deno.md

 - Elysia on Deno
-

drizzle.md

 - Integrate Elysia with Drizzle ORM
-

expo.md

 - Elysia in Expo API route
-

nextjs.md

 - Elysia in Nextjs API route
-

nodejs.md

 - Run Elysia on Node.js
-

nuxt.md

 - Elysia on API route
-

prisma.md

 - Integrate Elysia with Prisma
-

react-email.d

 - Create and Send Email with React and Elysia
-

sveltekit.md

 - Run Elysia on Svelte Kit API route
-

tanstack-start.md

 - Run Elysia on Tanstack Start / React Query
-

vercel.md

 - Deploy Elysia to Vercel

### examples/ (optional)
-

basic.ts

 - Basic Elysia example
-

body-parser.ts - Custom body parser example via .onParse

complex.ts

 - Comprehensive usage of Elysia server
-

cookie.ts

 - Setting cookie
-

error.ts

 - Error handling
-

file.ts

 - Returning local file from server
-

guard.ts

 - Setting mulitple validation schema and lifecycle
-

map-response.ts

 - Custom response mapper
-

redirect.ts

 - Redirect response
-

rename.ts

 - Rename context's property 
-

schema.ts

 - Setup validation
-

state.ts

 - Setup global state
-

upload-file.ts

 - File upload with validation
-

websocket.ts

 - Web Socket for realtime communication

### patterns/ (optional)
-

patterns/mvc.md` - Detail guideline for using Elysia with MVC patterns

By elysiajs

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/elysia/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/elysiajs/skills/elysia/SKILL.md
Cursor: ~/.cursor/skills/elysiajs/skills/elysia/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/elysiajs/skills/elysia/SKILL.md

🚀 Install with CLI:
npx skills add elysiajs/skills

Read the Master Guide: Mastering Agent Skills →

Recommended Rules

View more rules →

Recommended Workflows

View more workflows →

Setup Redis Caching

BackendCachingPerformance

--- description: Implement Redis caching (Upstash or self-hosted) --- 1. **Option A: Upstash Redis (Serverless Recommended)**: - Best for Vercel/E...

Generate TypeScript Types from API

TypeScriptAPICodegen

--- description: Auto-generate type-safe API client from OpenAPI/Swagger spec --- 1. **Get Your API Schema**: - Most APIs expose OpenAPI spec at `...

Analyze Bundle Size

PerformanceNext.jsOptimization

--- description: Visualize and reduce your production build size --- 1. **Install Analyzer**: - Install the Next.js bundle analyzer. // turbo ...

Recommended MCP Servers

View more MCP servers →

Buildable

Official

(TypeScript) - Official MCP server for Buildable AI-powered development platform. Enables AI assistants to manage tasks, track progress, get project context, and collaborate with humans on software projects.

CloudBase

Official

One-stop backend services for WeChat Mini-Programs and full-stack apps with serverless cloud functions and databases by [Tencent CloudBase](https://tcb.cloud.tencent.com/)