elysia

library1.1.1jsnpmunverified

Elysia is a high-performance, ergonomic web framework built specifically for the Bun runtime, emphasizing end-to-end type safety and an exceptional developer experience. It provides a comprehensive set of features for building web servers and APIs, including robust routing, middleware, declarative schema validation (powered by `@sinclair/typebox`), and integrated WebSocket support. The framework is currently stable at version 1.4.28 and maintains a rapid release cadence, frequently incorporating improvements and bug fixes, often in synergy with Bun's development. Its core differentiators include native integration with Bun for superior performance, extensive TypeScript support providing compile-time and runtime type integrity, and a strong focus on developer productivity. Elysia aims to offer a unified type system where types serve as a single source of truth across the application, from API definition to automatic documentation generation, streamlining development and reducing errors.

web-framework http-networking serialization

npm install elysia

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ELYSIA

elysia

web-frameworkjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Elysia

✓ import { Elysia } from 'elysia'

✗ const Elysia = require('elysia'); // Elysia is ESM-only and Bun-native new Elysia(); // Incorrect instantiation, it's a class

Elysia is primarily designed for ESM and the Bun runtime. The `new Elysia()` syntax is correct after the ESM import.

✓ import { t } from 'elysia'

✗ import { Type } from '@sinclair/typebox'; // While TypeBox, Elysia re-exports its own 't'

The `t` object is Elysia's re-export of TypeBox for schema definitions. It's the idiomatic way to define schemas within Elysia applications.

handle

✓ import { handle } from 'elysia'

The `handle` function is used for programmatically handling requests, often for testing or custom server integrations.

This quickstart sets up a basic Elysia server with a GET route, a POST route with schema validation using `t` (TypeBox), and a simple WebSocket endpoint. It demonstrates common routing, body parsing, and schema definition patterns, then starts the server on port 3000.

import { Elysia, t } from 'elysia' const app = new Elysia() .get('/', () => 'Hello Elysia!') .post('/greet', ({ body }) => `Hello, ${body.name}!`, { body: t.Object({ name: t.String({ minLength: 1, description: 'The name of the person to greet.' }) }), detail: { summary: 'Greets a person by name', description: 'Accepts a JSON body with a `name` property and returns a greeting.' } }) .ws('/chat', { message(ws, message) { ws.send(`Echo: ${message}`); }, open(ws) { console.log('WebSocket client connected'); ws.send('Welcome to the chat!'); }, close() { console.log('WebSocket client disconnected'); } }) .listen(3000, () => { console.log(`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`); }); export type App = typeof app;

Debug

Known issues

breakingElysia 1.4.19 introduced a security fix that rejects invalid cookie signatures when using cookie rotation. This change, while enhancing security, may cause issues with clients using previously signed but now invalid cookies.

fix

Ensure all clients clear their old cookies or handle potential `401 Unauthorized` responses for routes relying on signed cookies. Implement robust cookie rotation strategies.

affects: >=1.4.19

gotchaWhen mounting Elysia instances using the `.group` or `.use` methods, incorrect URL path resolution can occur, especially with instances that have a `prefix` option or specific trailing path configurations. This could lead to routes not being matched as expected.

fix

Review your `mount` and `group` configurations. Ensure consistent trailing slashes and prefix handling across your application. Updates in 1.4.26 address some of these issues, so upgrading is recommended.

affects: >=1.4.0 <1.4.26

gotchaDynamic imports located within `.guard` functions might not register routes correctly, leading to routes being inaccessible or not applying their guards as intended. This was a known bug in earlier 1.x versions.

fix

Upgrade to Elysia 1.4.28 or newer, which includes a fix for this issue. Avoid dynamic imports directly within `.guard` in older versions or refactor to ensure routes are registered before guards are evaluated.

affects: >=1.0.0 <1.4.28

gotchaElysia is primarily optimized for and runs on the Bun runtime. While it may run on Node.js with some polyfills or compatibility layers, performance and certain features (like native file streaming) are best experienced with Bun. Many community plugins are also Bun-specific.

fix

For optimal performance and full feature compatibility, use Elysia with the latest stable version of Bun. If using Node.js, anticipate potential compatibility issues or performance degradation.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'elysia'

This typically occurs when trying to run an Elysia application with `node` instead of `bun`, or if using CommonJS `require()` syntax with a package that is ESM-only.

fix

Ensure you are running your application with `bun run <your_file.ts>` or `bun start`. If using TypeScript, ensure your `tsconfig.json` targets `ESNext` modules. Always use `import` statements for Elysia.

Elysia is not a constructor

This error arises when attempting to instantiate Elysia using `new Elysia()` after importing it incorrectly, often with a CommonJS `require()` statement that doesn't resolve the default export correctly, or if bundlers misinterpret the import.

fix

Verify that you are using an ESM import: `import { Elysia } from 'elysia'`. If this persists, check your `tsconfig.json`'s `module` and `moduleResolution` settings (e.g., `"module": "ESNext", "moduleResolution": "bundler"` or `"node16"`).

Validation Error: 'body.name' expected string, received undefined

This error indicates that an incoming request body failed schema validation. In this example, the `name` property within the request body was expected to be a string but was either missing or of an incorrect type.

fix

Check the incoming request's JSON body to ensure it matches the `t.Object` schema defined for the route. For this error, the request body should be `{"name": "some string"}`.

Failed to listen on port 3000. Address already in use.

Another process is already using the specified port (e.g., 3000). This is a common operating system error.

fix

Change the port number in your `.listen()` call (e.g., `app.listen(4000)`). Alternatively, identify and terminate the process currently using the port (e.g., `lsof -i :3000` on Unix-like systems, `netstat -ano | findstr :3000` on Windows).

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

@types/bunrequiredProvides TypeScript type definitions for the Bun runtime environment.

@sinclair/typeboxrequiredEssential for defining and validating schemas for request bodies, queries, and responses.

openapi-typesoptionalUsed for generating OpenAPI (Swagger) documentation based on defined schemas.

typescriptoptionalRequired for type checking and compilation, given Elysia's strong TypeScript focus.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/elysiajs/elysia ↗

packagehttps://www.npmjs.com/package/elysia ↗

homepagehttps://elysiajs.com ↗