Config

Elysia comes with a configurable behavior, allowing us to customize various aspects of its functionality.

We can define a configuration by using a constructor.

import { Elysia, t } from 'elysia'

new Elysia({
	prefix: '/v1',
	normalize: true
})

adapter

Since 1.1.11

Runtime adapter for using Elysia in different environments.

Defaults to appropriate adapter based on the environment.

import { Elysia, t } from 'elysia'
import { BunAdapter } from 'elysia/adapter/bun'

new Elysia({
	adapter: BunAdapter
})

allowUnsafeValidationDetails

Since 1.4.13

Whether Elysia should include unsafe validation details in the error response on production.

import { Elysia, t } from 'elysia'

new Elysia({
	allowUnsafeValidationDetails: true
})

By default, Elysia will omit all validation detail on production.

This is done to prevent leaking sensitive information about the validation schema, such as field names and expected types, which could be exploited by an attacker.

Ideally, this should only be enabled on public APIs as it may leak sensitive information about the server implementation.

Options - @default false

• true - Include unsafe validation details in the error response on production
• false - Exclude unsafe validation details in the error response on production

aot

Since 0.4.0

Ahead of Time compilation.

Elysia has a built-in JIT "compiler" that can optimize performance.

import { Elysia } from 'elysia'

new Elysia({
	aot: true
})

Disable Ahead of Time compilation

Options - @default false

• true - Precompile every route before starting the server

• false - Disable JIT entirely. Faster startup time without cost of performance

detail

Define an OpenAPI schema for all routes of an instance.

This schema will be used to generate OpenAPI documentation for all routes of an instance.

import { Elysia } from 'elysia'

new Elysia({
	detail: {
		hide: true,
		tags: ['elysia']
	}
})

encodeSchema

Handle custom t.Transform schemas with custom Encode before returning the response to client.

This allows us to create custom encode functions for your data before sending response to the client.

import { Elysia, t } from 'elysia'

new Elysia({ encodeSchema: true })

Options - @default true

• true - Run Encode before sending the response to client
• false - Skip Encode entirely

name

Define the name of an instance which is used for debugging and Plugin Deduplication

import { Elysia } from 'elysia'

new Elysia({
	name: 'service.thing'
})

nativeStaticResponse

Since 1.1.11

Use optimized functions for handling inline values for each respective runtime.

import { Elysia } from 'elysia'

new Elysia({
	nativeStaticResponse: true
})

Example

If enabled on Bun, Elysia will insert inline value into Bun.serve.static improving performance for static value.

import { Elysia } from 'elysia'

// This
new Elysia({
	nativeStaticResponse: true
}).get('/version', 1)

// is an equivalent to
Bun.serve({
	static: {
		'/version': new Response(1)
	}
})

normalize

Since 1.1.0

Whether Elysia should coerce fields into a specified schema.

import { Elysia, t } from 'elysia'

new Elysia({
	normalize: true
})

When unknown properties that are not specified in schema are found on either input and output, how should Elysia handle the field?

Options - @default true

• true: Elysia will coerce fields into a specified schema using exact mirror

• typebox: Elysia will coerce fields into a specified schema using TypeBox's Value.Clean

• false: Elysia will raise an error if a request or response contains fields that are not explicitly allowed in the schema of the respective handler.

precompile

Since 1.0.0

Whether Elysia should precompile all routes ahead of time before starting the server.

import { Elysia } from 'elysia'

new Elysia({
	precompile: true
})

Options - @default false

• true: Run JIT on all routes before starting the server

• false: Dynamically compile routes on demand

It's recommended to leave it as false.

prefix

Define a prefix for all routes of an instance

import { Elysia, t } from 'elysia'

new Elysia({
	prefix: '/v1'
})

When prefix is defined, all routes will be prefixed with the given value.

Example

import { Elysia, t } from 'elysia'

new Elysia({ prefix: '/v1' }).get('/name', 'elysia') // Path is /v1/name

sanitize

A function or an array of functions that calls and intercepts on every t.String while validation.

Allowing us to read and transform strings into new values.

import { Elysia, t } from 'elysia'

new Elysia({
	sanitize: (value) => Bun.escapeHTML(value)
})

seed

Define a value that will be used to generate checksum of an instance, used for Plugin Deduplication

import { Elysia } from 'elysia'

new Elysia({
	seed: {
		value: 'service.thing'
	}
})

The value could be any type not limited to string, number, or object.

strictPath

Whether Elysia should handle paths strictly.

According to RFC 3986, a path should be strictly equal to the path defined in the route.

import { Elysia, t } from 'elysia'

new Elysia({ strictPath: true })

Options - @default false

• true - Follows RFC 3986 for path matching strictly
• false - Tolerate suffix '/' or vice-versa.

Example

import { Elysia, t } from 'elysia'

// Path can be either /name or /name/
new Elysia({ strictPath: false }).get('/name', 'elysia')

// Path can be only /name
new Elysia({ strictPath: true }).get('/name', 'elysia')

serve

Customize HTTP server behavior.

Bun serve configuration.

import { Elysia } from 'elysia'

new Elysia({
	serve: {
		hostname: 'elysiajs.com',
		tls: {
			cert: Bun.file('cert.pem'),
			key: Bun.file('key.pem')
		}
	},
})

This configuration extends Bun Serve API and Bun TLS

Example: Max body size

We can set the maximum body size by setting serve.maxRequestBodySize in the serve configuration.

import { Elysia } from 'elysia'

new Elysia({
	serve: {
		maxRequestBodySize: 1024 * 1024 * 256 // 256MB
	}
})

By default the maximum request body size is 128MB (1024 * 1024 * 128). Define body size limit.

import { Elysia } from 'elysia'

new Elysia({
	serve: {
		// Maximum message size (in bytes)
	    maxPayloadLength: 64 * 1024,
	}
})

Example: HTTPS / TLS

We can enable TLS (known as successor of SSL) by passing in a value for key and cert; both are required to enable TLS.

import { Elysia, file } from 'elysia'

new Elysia({
	serve: {
		tls: {
			cert: file('cert.pem'),
			key: file('key.pem')
		}
	}
})

Example: Increase timeout

We can increase the idle timeout by setting serve.idleTimeout in the serve configuration.

import { Elysia } from 'elysia'

new Elysia({
	serve: {
		// Increase idle timeout to 60 seconds
		idleTimeout: 60
	}
})

By default the idle timeout is 30 seconds.

---

serve

HTTP server configuration.

Elysia extends Bun configuration which supports TLS out of the box, powered by BoringSSL.

See serve.tls for available configuration.

serve.hostname

@default 0.0.0.0

Set the hostname which the server listens on

serve.id

Uniquely identify a server instance with an ID

This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

serve.idleTimeout

@default 30 (30 seconds)

By default, Elysia sets idle timeout to 30 seconds, which means that if a request is not completed within 30 seconds, it will be aborted.

serve.maxRequestBodySize

@default 1024 * 1024 * 128 (128MB)

Set the maximum size of a request body (in bytes)

serve.port

@default 3000

Port to listen on

serve.rejectUnauthorized

@default NODE_TLS_REJECT_UNAUTHORIZED environment variable

If set to false, any certificate is accepted.

serve.reusePort

@default true

If the SO_REUSEPORT flag should be set

This allows multiple processes to bind to the same port, which is useful for load balancing

This configuration is overridden and turns on by default by Elysia

serve.unix

If set, the HTTP server will listen on a unix socket instead of a port.

(Cannot be used with hostname+port)

serve.tls

We can enable TLS (known as successor of SSL) by passing in a value for key and cert; both are required to enable TLS.

import { Elysia, file } from 'elysia'

new Elysia({
	serve: {
		tls: {
			cert: file('cert.pem'),
			key: file('key.pem')
		}
	}
})

Elysia extends Bun configuration which supports TLS out of the box, powered by BoringSSL.

serve.tls.ca

Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla.

Mozilla's CAs are completely replaced when CAs are explicitly specified using this option.

serve.tls.cert

Cert chains in PEM format. One cert chain should be provided per private key.

Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca).

When providing multiple cert chains, they do not have to be in the same order as their private keys in key.

If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.

serve.tls.dhParamsFile

File path to a .pem file custom Diffie Helman parameters

serve.tls.key

Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with options.passphrase.

Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form .

The object form can only occur in an array.

object.passphrase is optional. Encrypted keys will be decrypted with

object.passphrase if provided, or options.passphrase if it is not.

serve.tls.lowMemoryMode

@default false

This sets OPENSSL_RELEASE_BUFFERS to 1.

It reduces overall performance but saves some memory.

serve.tls.passphrase

Shared passphrase for a single private key and/or a PFX.

serve.tls.requestCert

@default false

If set to true, the server will request a client certificate.

serve.tls.secureOptions

Optionally affect the OpenSSL protocol behavior, which is not usually necessary.

This should be used carefully if at all!

Value is a numeric bitmask of the SSL_OP_* options from OpenSSL Options

serve.tls.serverName

Explicitly set a server name

tags

Define tags for OpenAPI schema for all routes of an instance similar to detail

import { Elysia } from 'elysia'

new Elysia({
	tags: ['elysia']
})

systemRouter

Use runtime/framework provided router if possible.

On Bun, Elysia will use Bun.serve.routes and fallback to Elysia's own router.

websocket

Override websocket configuration

Recommended to leave this as default as Elysia will generate suitable configuration for handling WebSocket automatically

This configuration extends Bun's WebSocket API

Example

import { Elysia } from 'elysia'

new Elysia({
	websocket: {
		// enable compression and decompression
    	perMessageDeflate: true
	}
})

---