Routing

On this page

1. Overview
2. Path types
3. Static path
4. Dynamic path
5. Access params
6. Optional params
7. Wildcard
8. Path priority
9. HTTP verbs
10. Custom method
11. All methods
12. Group
13. Prefix

1. Docs
2. Essential
3. Routing

Copy page

Routing

A REST API takes a path and method to decide which handler to run.

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Elysia')
    .get('/hi', 'Hello!')
    .listen(3000)

GET /

Elysia

Calling .listen will start a web server at port 3000.

We can access our server by going to http://localhost:3000.

• / with the GET method will return Elysia.
• /hi with the GET method will return Hello!.
• Any other path will return a 404.

Visiting a URL in your browser sends a GET request.

Path types

Paths can be grouped into 3 types:

1. Static paths

   exact match

2. Dynamic paths

   some parts are dynamic, and can be captured as parameters

3. Wildcards

   match the rest of a path

Static path

A static path is an exact match, with no surprises.

• / matches only /
• /hi matches only /hi

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/hi', 'Hi')
    .listen(3000)

Dynamic path

Add : followed by a name to capture its value.

/user/:id matches /user/42, /user/abc, and /user/hello-world.

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/user/:id', () => 'hello user')
    .listen(3000)

Access params

Read the matched value from params in your handler.

When /user/42/profile matches /user/:id/profile, params.id is 42. The handler returns it as the response.

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/user/:id', () => 'hello user')
    .get('/user/:id/profile', ({ params: { id } }) => id)
    .listen(3000)

Optional params

Add ? after a parameter name to make it optional.

/user/:id?/profile matches both /user/42/profile and /user/profile.

The value will be undefined if the parameter is not present.

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/user/:id', () => 'hello user')
    .get('/user/:id?/profile', ({ params: { id } }) => id)
    .listen(3000)

Wildcard

Adding * at the end of a path will match any path after it.

/user/* matches multi-segment paths such as /user/hello-world/profile. In this example, /user/42 still goes to /user/:id, because dynamic paths take priority over wildcards (see path priority).

For /user/hello-world/profile, params['*'] is hello-world/profile.

import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/user/:id', () => 'hello user')
    .get('/user/*', ({ params }) => params['*'])
    .listen(3000)

1 / 5

In this example: Static path

					import { Elysia } from 'elysia'

new Elysia()
    .get('/', 'Hello Elysia')
    .get('/hi', 'Hi')
    .listen(3000)

				

Path priority

Elysia will resolve paths in the following order:

1. static paths
2. dynamic paths
3. wildcards

import { Elysia } from 'elysia'

new Elysia()
    .get('/user/1', 'Hello Elysia')
    .get('/user/:id', ({ params: { id } }) => id)
    .get('/user/*', ({ params }) => params['*'])
    .listen(3000)

GET /user/1

Hello Elysia

---

HTTP verbs

HTTP verbs are the methods of requests, such as GET, POST, or PUT.

GET

Get data from the server. Browsers use it to visit a page.

HEAD

Similar to GET, but only returns the headers, not the body.

POST

Send data to the server, often to create a resource.

PUT

Replace a resource with the data you send.

PATCH

Update part of a resource.

DELETE

Delete a resource.

To define a standard method, use the corresponding method on the Elysia instance:

import { Elysia } from 'elysia'

new Elysia()
  .get('/', 'Hi GET!')
  .post('/', 'Hi POST!')
  .put('/', 'Hi PUT!')
  .patch('/', 'Hi PATCH!')
  .delete('/', 'Hi DELETE!')
  .listen(3000)

Custom method

Define using .method with the method name as the first argument. The rest is the same as other methods.

import { Elysia } from 'elysia'

new Elysia()
  .method('PROPFIND', '/', 'Hi PROPFIND!')
  .listen(3000)

All methods

Catch all methods using .all:

import { Elysia } from 'elysia'

new Elysia()
  .all('/', 'Hi ALL!')
  .listen(3000)

---

Group

Many paths with the same prefix can be grouped using .group:

import { Elysia } from 'elysia'

new Elysia()
    .group('/user', (app) =>
        app
            .post('/sign-in', 'Sign in')
            .get('/profile', 'Profile')
    )
    .listen(3000)

POST /user/sign-in

Sign in

It’s similar to writing /user/sign-in and /user/profile separately.

Prefix

If the entire instance has the same prefix, we can define it in the constructor:

import { Elysia } from 'elysia'

new Elysia({ prefix: '/user' })
    .post('/sign-in', 'Sign in')
    .get('/profile', 'Profile')

POST /user/sign-in

Sign in

This is different from .group because the prefix is applied to all paths in the instance while group applies to the paths in the callback.