{"id":10784,"library":"elysia","title":"Elysia Web Framework","description":"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.","status":"active","version":"1.4.28","language":"javascript","source_language":"en","source_url":"https://github.com/elysiajs/elysia","tags":["javascript","bun","http","web","server","typescript"],"install":[{"cmd":"npm install elysia","lang":"bash","label":"npm"},{"cmd":"yarn add elysia","lang":"bash","label":"yarn"},{"cmd":"pnpm add elysia","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides TypeScript type definitions for the Bun runtime environment.","package":"@types/bun","optional":false},{"reason":"Essential for defining and validating schemas for request bodies, queries, and responses.","package":"@sinclair/typebox","optional":false},{"reason":"Used for generating OpenAPI (Swagger) documentation based on defined schemas.","package":"openapi-types","optional":true},{"reason":"Required for type checking and compilation, given Elysia's strong TypeScript focus.","package":"typescript","optional":true}],"imports":[{"note":"Elysia is primarily designed for ESM and the Bun runtime. The `new Elysia()` syntax is correct after the ESM import.","wrong":"const Elysia = require('elysia'); // Elysia is ESM-only and Bun-native\nnew Elysia(); // Incorrect instantiation, it's a class","symbol":"Elysia","correct":"import { Elysia } from 'elysia'"},{"note":"The `t` object is Elysia's re-export of TypeBox for schema definitions. It's the idiomatic way to define schemas within Elysia applications.","wrong":"import { Type } from '@sinclair/typebox'; // While TypeBox, Elysia re-exports its own 't'","symbol":"t","correct":"import { t } from 'elysia'"},{"note":"The `handle` function is used for programmatically handling requests, often for testing or custom server integrations.","symbol":"handle","correct":"import { handle } from 'elysia'"}],"quickstart":{"code":"import { Elysia, t } from 'elysia'\n\nconst app = new Elysia()\n  .get('/', () => 'Hello Elysia!')\n  .post('/greet', ({ body }) => `Hello, ${body.name}!`, {\n    body: t.Object({\n      name: t.String({\n        minLength: 1,\n        description: 'The name of the person to greet.'\n      })\n    }),\n    detail: {\n      summary: 'Greets a person by name',\n      description: 'Accepts a JSON body with a `name` property and returns a greeting.'\n    }\n  })\n  .ws('/chat', {\n    message(ws, message) {\n      ws.send(`Echo: ${message}`);\n    },\n    open(ws) {\n      console.log('WebSocket client connected');\n      ws.send('Welcome to the chat!');\n    },\n    close() {\n      console.log('WebSocket client disconnected');\n    }\n  })\n  .listen(3000, () => {\n    console.log(`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`);\n  });\n\nexport type App = typeof app;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Elysia 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.","severity":"breaking","affected_versions":">=1.4.19"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.4.0 <1.4.26"},{"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.","message":"Dynamic 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.","severity":"gotcha","affected_versions":">=1.0.0 <1.4.28"},{"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.","message":"Elysia 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Cannot find module 'elysia'"},{"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\"`).","cause":"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.","error":"Elysia is not a constructor"},{"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\"}`.","cause":"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.","error":"Validation Error: 'body.name' expected string, received undefined"},{"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).","cause":"Another process is already using the specified port (e.g., 3000). This is a common operating system error.","error":"Failed to listen on port 3000. Address already in use."}],"ecosystem":"npm"}