Elysia Web Framework

Common errors

• Error: Cannot find module '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.
  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

  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.
  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

  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.
  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.

  cause 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).

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install elysia npm
• yarn add elysia yarn
• pnpm add elysia pnpm

Imports

• Elysia
  wrong:

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

  correct:

  import { Elysia } from 'elysia'

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

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

  correct:

  import { t } from 'elysia'

  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.

Quickstart

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;