Skip to content
Our Sponsors
Open in Anthropic

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:

Additional Property

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)
localhost

GET

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.

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