Elysia: TypeScript HTTP Framework Optimized for Bun

What Problem Elysia Solves and Who It Is For

TypeScript HTTP frameworks on Node.js typically bolt type safety on top of an untyped core, meaning route handlers, request body parsing, and response serialization all require manual type assertions that the compiler cannot verify end-to-end. Elysia starts from the other direction: type safety is a design goal, not an afterthought, and the framework's description sums up the intent as "TypeScript with End-to-End Type Safety, type integrity, and exceptional developer experience."

The primary audience is TypeScript developers who want request and response types to flow from a single schema definition to the handler and outward to the response, with the compiler catching mismatches rather than a runtime error. The secondary requirement is Bun: the README describes the framework as "Supercharged by Bun," meaning peak performance is tied to running on Bun's runtime.

The framework is not a general-purpose server-side framework in the style of NestJS or Next.js. It handles HTTP routing, middleware, and WebSocket management, but it does not include an ORM layer, a templating engine for server-rendered HTML, or a built-in database connection pool. Teams assembling a full stack will combine Elysia with other packages for those responsibilities.

Package Structure and Module Layout

Elysia's npm package exports multiple named sub-modules beyond the root entry point. The `elysia/ws` sub-path provides the WebSocket API and its associated types. The `elysia/schema` sub-path exposes the schema definition utilities. Additional exports cover `elysia/context`, `elysia/cookies`, `elysia/error`, `elysia/trace`, `elysia/compose`, and `elysia/type-system`.

This modular export design means consuming code imports only the pieces it uses, keeping bundle sizes predictable. The separate WebSocket module in particular (`elysia/ws`, `elysia/ws/bun`) signals that Bun's native WebSocket API has its own dedicated integration path rather than being mapped through a compatibility layer.

The source lives under `src/`, compiled outputs go to `dist/` in both ESM (`.mjs`) and CommonJS (`.js`) formats, with TypeScript declarations alongside each. The project uses `bun.lock` for dependency management, confirming that Bun is the development runtime.

Getting Started: Scaffolding and First Routes

The README includes a scaffolding command for creating a new Elysia project:

bun create elysia app

This generates a new directory named `app` with the project structure. The full documentation covering route definitions, handler signatures, and startup configuration is at elysiajs.com.

The repository's `example/` directory contains reference implementations covering the main APIs. `example/params.ts` shows URL parameter extraction. `example/body.ts` demonstrates request body handling. `example/cookie.ts` covers cookie reading and writing. `example/headers.ts` shows header access. `example/guard.ts` shows route guards. `example/hook.ts` demonstrates the hook lifecycle. `example/openapi.ts` covers the OpenAPI schema generation.

The example files use `.ts` throughout, confirming the entire authoring experience is TypeScript-first. There is no JavaScript fallback path in the examples.

Schema Validation, Guards, and the Hook Lifecycle

Elysia's design centers on a schema-first approach to request validation. The `elysia/schema` export provides the definitions that both validate incoming requests at runtime and drive TypeScript inference in handlers. Declaring a schema for a route's body or query parameters means the handler receives a correctly typed value without additional casting.

The `example/guard.ts` file indicates a guard mechanism for protecting routes or groups of routes, and `example/nested-schema.ts` shows that schemas compose for complex nested request shapes.

The hook system, visible in `example/hook.ts`, provides lifecycle interception points before and after handler execution. These map to common middleware patterns: authentication, request logging, and response transformation. The `example/derive.ts` file covers the derive API, which makes context values derived from the request (such as a parsed user from a token) available to handlers with full type inference.

Lazy module loading is available through `example/lazy-module.ts` and the `example/lazy/` directory. This defers loading a route handler module until the first request hits that path, which matters for startup time when the application defines many routes.

Built-in WebSocket, File Uploads, and Proxy Support

WebSocket handling is a first-class feature with its own dedicated sub-module and Bun-specific integration (`elysia/ws/bun`). The `example/` directory does not contain a WebSocket example by name, but the dedicated export path indicates the API is a supported part of the framework rather than a plugin dependency.

File uploads appear in `example/nested-multipart-files.ts`, which handles multipart form data with nested file fields. This covers the common pattern of file upload endpoints where a single request carries multiple file fields.

Proxy routing is available as shown in `example/proxy.ts`, enabling Elysia to forward requests to a backend service. This is useful for API gateway patterns where Elysia sits in front of other services.

HTML responses are covered in `example/html-import.ts`, and custom response formats are in `example/custom-response.ts`. The OpenAPI integration in `example/openapi.ts` generates API documentation directly from the schema definitions attached to routes, removing the need to maintain a separate specification file.

Limitations and Cases Where Elysia Is the Wrong Choice

The framework is described as "Supercharged by Bun," which means performance benchmarks and some features are Bun-specific. Teams on standard Node.js who cannot migrate to Bun will not get the full value from Elysia and should choose a framework designed around Node.js internals.

The README provides almost no inline documentation: it shows the project name, a tagline, and links to elysiajs.com for the actual documentation. This means the repository itself is not a usable reference guide; anyone evaluating the framework must rely on the external documentation site, which the article cannot assess because it is outside the material.

Elysia does not include database integration, an ORM, or built-in session management. Teams coming from frameworks like AdonisJS or NestJS, which bundle these facilities, will need to select and integrate each component separately.

Error handling is an explicit concern: `example/error.ts` is included, but error handling in distributed systems (circuit breakers, structured error responses, retry logic) is not documented in the README and falls to the application developer.

Elysia vs Hono: Two Bun-Compatible TypeScript Frameworks

Hono is an open source TypeScript HTTP framework that runs on Bun, Deno, Cloudflare Workers, Node.js, and other runtimes. Its multi-runtime design is a central feature: the same Hono application code can deploy to a Cloudflare Worker or a Bun process without code changes, making it the default choice for teams that need runtime portability.

Elysia's stated focus is on developer experience and type safety within the Bun ecosystem. Its end-to-end type system, covering the path from schema definition through request handling to response, is a deeper integration than Hono's type utilities, which are more lightweight to accommodate the broader runtime target.

The choice comes down to deployment requirements. A team deploying exclusively to Bun servers and prioritising compile-time safety is in Elysia's target profile. A team that may need to deploy the same codebase to Cloudflare Workers or Node.js in different environments should evaluate Hono's multi-runtime guarantees before committing to Elysia.

Both are MIT-licensed and actively maintained. Elysia's last push was on 2026-09-24, and the current release is 1.4.30.

Editorial conclusion

Elysia fits TypeScript teams that have adopted Bun as their primary runtime and want a framework where the type system covers routes, request bodies, cookies, and responses without manual assertion layers. Teams not yet on Bun, or those that need portability across Node.js and Cloudflare Workers in the same codebase, should evaluate Hono first. Before adopting Elysia in production, check the full documentation at elysiajs.com for the deployment configuration that matches your target environment.

Frequently asked questions

Official sources

1. elysiajs/elysia on GitHub
2. License: MIT
3. Project website
4. README
5. Releases