Handler

Handler - a function that accept an HTTP request, and return a response.

typescript

import { Elysia } from 'elysia'

new Elysia()
    // the function `() => 'hello world'` is a handler
    .get('/', () => 'hello world')
    .listen(3000)

A handler may be a literal value, and can be inlined.

typescript

import { Elysia, file } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/video', file('kyuukurarin.mp4'))
    .listen(3000)

Using an inline value always returns the same value which is useful to optimize performance for static resources like files.

This allows Elysia to compile the response ahead of time to optimize performance.

TIP

Providing an inline value is not a cache.

Static resource values, headers and status can be mutated dynamically using lifecycle.

Context

Context contains request information which is unique for each request, and is not shared except for store (global mutable state).

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
	.get
('/', (context
) => context
.path
)
            // ^ This is a context

Context can only be retrieved in a route handler. It consists of:

Property

body - HTTP message, form or file upload.
query - Query String, include additional parameters for search query as JavaScript Object. (Query is extracted from a value after pathname starting from '?' question mark sign)
params - Elysia's path parameters parsed as JavaScript object
headers - HTTP Header, additional information about the request like User-Agent, Content-Type, Cache Hint.
cookie - A global mutable signal store for interacting with Cookie (including get/set)
store - A global mutable store for Elysia instance

Utility Function

redirect - A function to redirect a response
status - A function to return custom status code
set - Property to apply to Response:
- headers - Response headers

Additional Property

request - Web Standard Request
server - Bun server instance
path - Pathname of the request

status

A function to return a custom status code with type narrowing.

typescript

import { Elysia } from 'elysia'

new Elysia()
    .get('/', ({ status }) => status(418, "Kirifuji Nagisa"))
    .listen(3000)

It's recommended use never-throw approach to return status instead of throw as it:

allows TypeScript to check if a return value is correctly type to response schema
autocompletion for type narrowing based on status code
type narrowing for error handling using End-to-end type safety (Eden)

Set

set is a mutable property that form a response accessible via Context.set.

import { Elysia
 } from 'elysia'

new Elysia
()
	.get
('/', ({ set
, status
 }) => {
		set
.headers
 = { 'X-Teapot': 'true' }

		return status
(418, 'I am a teapot')
	})
	.listen
(3000)

set.headers

Allowing us to append or delete response headers represented as an Object.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
    .get
('/', ({ set
 }) => {
        set
.headers
['x-powered-by'] = 'Elysia'

        return 'a mimir'
    })
    .listen
(3000)

TIP

Elysia provide an auto-completion for lowercase for case-sensitivity consistency, eg. use set-cookie rather than Set-Cookie.

redirect Legacy

Redirect a request to another resource.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
    .get
('/', ({ redirect
 }) => {
        return redirect
('https://youtu.be/whpVWVWBW4U?&t=8')
    })
    .get
('/custom-status', ({ redirect
 }) => {
        // You can also set custom status to redirect
        return redirect
('https://youtu.be/whpVWVWBW4U?&t=8', 302)
    })
    .listen
(3000)

When using redirect, returned value is not required and will be ignored. As response will be from another resource.

set.status Legacy

Set a default status code if not provided.

It's recommended to use this in a plugin that only needs to return a specific status code while allowing the user to return a custom value. For example, HTTP 201/206 or 403/405, etc.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
    .onBeforeHandle
(({ set
 }) => {
        set
.status
 = 418

        return 'Kirifuji Nagisa'
    })
    .get
('/', () => 'hi')
    .listen
(3000)

Unlike status function, set.status cannot infer the return value type, therefore it can't check if the return value is correctly type to response schema.

TIP

HTTP Status indicates the type of response. If the route handler is executed successfully without error, Elysia will return the status code 200.

You can also set a status code using the common name of the status code instead of using a number.

typescript

// @errors 2322
import { Elysia
 } from 'elysia'

new Elysia
()
    .get
('/', ({ set
 }) => {
        set
.status


        return 'Kirifuji Nagisa'
    })
    .listen
(3000)

Elysia provides a mutable signal for interacting with Cookie.

There's no get/set, you can extract the cookie name and retrieve or update its value directly.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
	.get
('/set', ({ cookie
: { name
 } }) => {
		// Get
        name
.value


        // Set
        name
.value
 = "New Value"
	})

See Patterns: Cookie for more information.

Redirect

Redirect a request to another resource.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
	.get
('/', ({ redirect
 }) => {
		return redirect
('https://youtu.be/whpVWVWBW4U?&t=8')
	})
	.get
('/custom-status', ({ redirect
 }) => {
		// You can also set custom status to redirect
		return redirect
('https://youtu.be/whpVWVWBW4U?&t=8', 302)
	})
	.listen
(3000)

When using redirect, returned value is not required and will be ignored. As response will be from another resource.

Formdata

We may return a FormData by using returning form utility directly from the handler.

typescript

import { Elysia, form, file } from 'elysia'

new Elysia()
	.get('/', () => form({
		name: 'Tea Party',
		images: [file('nagi.web'), file('mika.webp')]
	}))
	.listen(3000)

This pattern is useful if even need to return a file or multipart form data.

Return a file

Or alternatively, you can return a single file by returning file directly without form.

typescript

import { Elysia, file } from 'elysia'

new Elysia()
	.get('/', file('nagi.web'))
	.listen(3000)

Stream

To return a response streaming out of the box by using a generator function with yield keyword.

typescript

import { Elysia } from 'elysia'

const app = new Elysia()
	.get('/ok', function* () {
		yield 1
		yield 2
		yield 3
	})

This this example, we may stream a response by using yield keyword.

Server Sent Events (SSE)

Elysia supports Server Sent Events by providing a sse utility function.

typescript

import { Elysia
, sse
 } from 'elysia'

new Elysia
()
	.get
('/sse', function* () {
		yield sse
('hello world')
		yield sse
({
			event
: 'message',
			data
: {
				message
: 'This is a message',
				timestamp
: new Date
().toISOString
()
			},
		})
	})

When a value is wrapped in sse, Elysia will automatically set the response headers to text/event-stream and format the data as an SSE event.

Headers in Server-Sent Event

Headers can only be set before the first chunk is yielded.

typescript

import { Elysia
 } from 'elysia'

const app
 = new Elysia
()
	.get
('/ok', function* ({ set
 }) {
		// This will set headers
		set
.headers
['x-name'] = 'Elysia'
		yield 1
		yield 2

		// This will do nothing
		set
.headers
['x-id'] = '1'
		yield 3
	})

Once the first chunk is yielded, Elysia will send the headers to the client, therefore mutating headers after the first chunk is yielded will do nothing.

Conditional Stream

If the response is returned without yield, Elysia will automatically convert stream to normal response instead.

typescript

import { Elysia } from 'elysia'

const app = new Elysia()
	.get('/ok', function* () {
		if (Math.random() > 0.5) return 'ok'

		yield 1
		yield 2
		yield 3
	})

This allows us to conditionally stream a response or return a normal response if necessary.

Automatic cancellation

Before response streaming is completed, if the user cancels the request, Elysia will automatically stop the generator function.

Eden

Eden will interpret a stream response as AsyncGenerator allowing us to use for await loop to consume the stream.

typescript

import { Elysia
 } from 'elysia'
import { treaty
 } from '@elysiajs/eden'

const app
 = new Elysia
()
	.get
('/ok', function* () {
		yield 1
		yield 2
		yield 3
	})

const { data
, error
 } = await treaty
(app
).ok
.get
()
if (error
) throw error


for await (const chunk
 of data
)
	console
.log
(chunk
)

Request

Elysia is built on top of Web Standard Request which is shared between multiple runtime like Node, Bun, Deno, Cloudflare Worker, Vercel Edge Function, and more.

typescript

import { Elysia } from 'elysia'

new Elysia()
	.get('/user-agent', ({ request }) => {
		return request.headers.get('user-agent')
	})
	.listen(3000)

Allowing you to access low-level request information if necessary.

Server Bun only

Server instance is a Bun server instance, allowing us to access server information like port number or request IP.

Server will only be available when HTTP server is running with listen.

typescript

import { Elysia } from 'elysia'

new Elysia()
	.get('/port', ({ server }) => {
		return server?.port
	})
	.listen(3000)

Request IP Bun only

We can get request IP by using server.requestIP method

typescript

import { Elysia } from 'elysia'

new Elysia()
	.get('/ip', ({ server, request }) => {
		return server?.requestIP(request)
	})
	.listen(3000)

Extends context Advance concept

Elysia provides a minimal Context by default, allowing us to extend Context for our specific need using state, decorate, derive, and resolve.

See Extends Context for more information on how to extend a Context.

Our Sponsors

Handler ​

Context ​

Property ​

Utility Function ​

Additional Property ​

status ​

Set ​

set.headers ​

Cookie ​

Redirect ​

Formdata ​

Return a file ​

Stream ​

Server Sent Events (SSE) ​

Headers in Server-Sent Event ​

Conditional Stream ​

Automatic cancellation ​

Eden ​

Request ​

Server Bun only ​

Request IP Bun only ​

Extends context Advance concept ​

Handler

Context

Property

Utility Function

Additional Property

status

Set

set.headers

Cookie

Redirect

Formdata

Return a file

Stream

Server Sent Events (SSE)

Headers in Server-Sent Event

Conditional Stream

Automatic cancellation

Eden

Request

Server Bun only

Request IP Bun only

Extends context Advance concept