Elysia est un framework HTTP écrit en TypeScript et construit autour du runtime Bun. La promesse est étroite et précise : un type de route défini côté serveur arrive chez le client sans génération de code ni interfaces maintenues à la main. La version stable actuelle est la 1.4.29, la licence est MIT, et le dépôt est elysiajs/elysia.
Ce qu'Elysia fait réellement
Elysia est un routeur HTTP avec validation des entrées intégrée, un cycle de vie des requêtes et la génération de documentation. L'interface est chaînée, et ce n'est pas une question de goût. Chaque appel à .get(), .post() ou .use() renvoie un nouveau type d'instance enrichi d'informations sur la route qui vient d'être ajoutée. Une fois l'application assemblée, typeof app contient une carte complète des chemins avec la forme du corps de la requête, des paramètres de requête et de la réponse. C'est le fondement sur lequel tout le reste repose : pas de chaîne, pas de type, et pas de type, pas de client Eden.
En dessous se trouve un compilateur qui génère le code de traitement de chaque route au démarrage au lieu d'interpréter la configuration à chaque requête. L'option aot le gouverne, activée par défaut et appuyée par une analyse statique du code des handlers nommée Sucrose. Si un handler ne touche jamais à body, le code généré saute entièrement l'analyse du corps. La même couche est responsable de nativeStaticResponse, qui confie les réponses constantes directement au serveur Bun.
La validation repose sur TypeBox, exposé via l'export t. Un schéma décrit par t.Object sert trois buts à la fois : il vérifie les données à l'exécution, dérive le type TypeScript pour le handler et devient une entrée du document OpenAPI. Elysia ajoute ses propres types utilitaires au-dessus de TypeBox, dont t.Numeric pour les valeurs numériques arrivant sous forme de texte, t.File et t.Files pour les envois de fichiers, ainsi que t.Form, t.UnionEnum, t.Nullable et t.ObjectString.
Ce qu'Elysia ne fait pas compte tout autant. Il n'y a pas de couche d'accès aux bases de données, donc Drizzle ORM ou Prisma restent un choix distinct. Il n'y a pas de rendu de vues côté serveur au sens de Next.js. Il n'y a pas d'authentification intégrée au-delà d'un plugin qui lit l'en-tête Bearer, donc la logique de session est à écrire ou à importer.
Version, licence et deux scopes npm
La version taguée latest est la 1.4.29, publiée le 16 juin 2026. Le paquet compte 749 versions derrière lui, ce qui, pour un dépôt créé en décembre 2022, donne un rythme très dense. Le travail sur la version deux se déroule en parallèle : le tag next pointe vers 2.0.0-beta.6 du 19 août 2026, et le tag experimental vers 2.0.0-exp.64. Cela signifie que la ligne stable n'a pas eu de version depuis juin alors que la branche principale est très vivante. Si tu prévois un déploiement qui se compte en années, prévois dans ton budget une migration vers la version deux.
La licence concorde dans les trois endroits où ce genre de choses diverge habituellement. Le fichier LICENSE de la branche principale contient le texte MIT avec la mention « Copyright 2022 saltyAom ». Le champ license dans le registre npm indique MIT. L'archive publiée elysia-1.4.29.tgz contient un fichier package/LICENSE identique octet pour octet à celui du dépôt. Le détecteur de licences de GitHub signale aussi MIT. C'est un cas rare d'accord complet, et un audit de dépendances n'a rien à clarifier ici.
Le scope de nommage cause bien plus de confusion. Les plugins existent sur npm en deux variantes : l'ancienne @elysiajs/ et la nouvelle @elysia/, publiées par le même mainteneur. L'adaptateur Node est @elysiajs/node en version 1.4.5 et @elysia/node en version 1.4.6. Le client est @elysiajs/eden en version 1.4.9 avec 110 versions derrière lui, et @elysia/eden en version 1.4.10 avec huit. La documentation du site du projet demande d'installer depuis le nouveau scope, alors que le README à l'intérieur du paquet Eden publié montre l'ancien scope avec l'ancienne interface, complète avec une fonction edenTreaty et une enveloppe schema qui n'existent plus. Au premier contact avec le projet, il est facile d'installer un paquet d'un scope et de copier un exemple écrit pour l'autre.
Il n'y a pas de variante payante. Le financement passe par GitHub Sponsors, et le projet est en pratique l'œuvre d'un seul auteur qui publie sous le compte aomkirby123. Cela comporte un risque connu : pas de contrat de support exécutoire, et un développement qui dépend de la disponibilité d'une seule personne.
Routes, validation et inférence de types
Installer et lancer prend une poignée de commandes.
# a new project from the scaffold
bun create elysia app
# or adding to an existing project
bun add elysia
# client and documentation
bun add @elysia/eden @elysia/openapi
# running with reload
bun --watch src/index.ts
# compiling to a single executable
bun build --compile --minify --sourcemap src/index.ts --outfile serverLe serveur lui-même ressemble à ceci. L'exemple ci-dessous n'utilise que des noms présents dans la version 1.4.29.
import { Elysia, t, status } from 'elysia'
import { openapi } from '@elysia/openapi'
const app = new Elysia({
prefix: '/api',
aot: true,
normalize: 'exactMirror',
strictPath: false,
nativeStaticResponse: true
})
.use(openapi())
.model({
user: t.Object({
id: t.Numeric(),
email: t.String({ format: 'email' }),
displayName: t.String({ minLength: 2, maxLength: 40 })
})
})
.state('requestCount', 0)
.derive(({ headers }) => ({
traceId: headers['x-trace-id'] ?? crypto.randomUUID()
}))
.get(
'/users',
({ query, store }) => {
store.requestCount += 1
return { items: [], page: query.page }
},
{
query: t.Object({
page: t.Numeric({ default: 1 }),
search: t.Optional(t.String())
}),
detail: { summary: 'User list', tags: ['users'] }
}
)
.post('/users', ({ body }) => body, {
body: 'user',
response: {
200: 'user',
409: t.Object({ message: t.String() })
}
})
.get('/users/:id', ({ params: { id } }) => {
if (id > 1000) return status(404, { message: 'Not found' })
return { id, email: 'a@b.com', displayName: 'Ada' }
}, {
params: t.Object({ id: t.Numeric() })
})
.onError(({ code, error, set }) => {
if (code === 'VALIDATION') {
set.status = 422
return { message: error.message }
}
})
.listen(3000)
export type App = typeof appPlusieurs points méritent un commentaire. Le champ body: 'user' renvoie à un schéma enregistré via .model(), donc la même forme alimente la validation, les types et le document OpenAPI depuis un seul endroit. La fonction status a remplacé l'ancienne error et renvoie une réponse avec un code précis tout en préservant ce code dans le type de la route. L'option normalize réglée sur exactMirror retire des réponses les champs absents du schéma, ce qui te protège de la fuite d'une colonne de mot de passe quand tu renvoies des lignes de base de données. La dernière ligne, export type App = typeof app, est tout le mécanisme d'export du contrat.
La logique répétée s'enveloppe dans une macro, qui attache à une route des événements de cycle de vie avec leurs types.
import { Elysia, status } from 'elysia'
const auth = new Elysia({ name: 'auth' }).macro({
requireUser: {
resolve({ headers }) {
const token = headers.authorization?.slice(7)
if (!token) return status(401, { message: 'Missing token' })
return { user: { id: 1, role: 'admin' as const } }
}
}
})
const routes = new Elysia()
.use(auth)
.get('/me', ({ user }) => user, { requireUser: true })Le champ user à l'intérieur du handler est connu du compilateur parce qu'il provient de resolve dans la macro. Il n'y a ni cast ni déclaration qui élargisse le type du contexte.
Eden, les mêmes types côté client
Eden est un client qui prend le type du serveur comme paramètre générique et en construit un objet qui reflète l'arbre des chemins. Le chemin /users/:id devient l'appel api.users({ id: 5 }).get(), et la méthode HTTP est le dernier appel de la chaîne.
import { treaty } from '@elysia/eden'
import type { App } from '../server/index'
const api = treaty<App>('localhost:3000', {
headers: { 'x-trace-id': crypto.randomUUID() }
})
const { data, error } = await api.api.users.get({
query: { page: 2, search: 'ada' }
})
if (error) {
switch (error.status) {
case 422:
console.error(error.value.message)
break
default:
throw error
}
}
console.log(data?.items)
const created = await api.api.users.post({
id: 7,
email: 'ada@example.com',
displayName: 'Ada'
})L'effet est le même que pour tRPC : changer la forme de la réponse côté serveur casse le build du client avant que quiconque lance l'application. La différence tient à la couche de transport. tRPC enveloppe les appels dans son propre format et exige son propre client de l'autre côté. Elysia expose des routes HTTP ordinaires qu'on peut appeler depuis curl, depuis une application mobile ou depuis un service écrit dans un autre langage, avec Eden comme ajout pour les clients TypeScript uniquement. En plus, le plugin OpenAPI produit un document qui décrit ces mêmes routes, donc un consommateur extérieur à l'écosystème obtient aussi un contrat.
La limite est réelle : séparer le serveur et le client dans deux dépôts casse l'arrangement, car typeof app doit être visible du compilateur côté client. Cela fonctionne dans un monorepo ou quand tu publies un paquet qui transporte les types. La seconde limite est le coût de compilation. Le type de l'instance grossit à chaque route, et à quelques centaines de routes le serveur de langage TypeScript ralentit nettement. Le remède est de découper l'application en instances plus petites reliées par .use().
Bun, Node et d'autres runtimes
Elysia a été créé pour Bun et c'est là que le chemin est le plus court : l'adaptateur elysia/adapter/bun est celui par défaut, listen correspond à Bun.serve, et les websockets fonctionnent sans bibliothèque supplémentaire. Le paquet ne déclare toutefois aucun champ engines, et le dossier dist/adapter contient trois variantes : bun, web-standard et cloudflare-worker.
Faire tourner sur Node est une vraie option et se résume à un réglage du constructeur.
import { Elysia } from 'elysia'
import { node } from '@elysia/node'
const app = new Elysia({ adapter: node() })
.get('/', () => 'Hello Node')
.listen(3000)
// the Deno variant: no listen, through Web Standard
// Deno.serve(app.fetch)
// the unit test variant, with no port opened
const response = await app.handle(
new Request('http://localhost/', { method: 'GET' })
)
console.log(response.status, await response.text())L'adaptateur Node repose sur les paquets srvx et crossws, qui font correspondre l'interface Web Standard à un serveur HTTP Node et aux websockets. Deno n'a besoin d'aucun adaptateur, puisque passer app.fetch à Deno.serve suffit. Cloudflare Workers ont leur propre adaptateur livré dans le paquet.
La couche d'adaptateurs ne lève toutefois pas la principale réserve. La documentation, les exemples, les plugins et les réponses de la communauté supposent tous Bun. Les plugins s'appuient sur des API de Bun, la compilation en un seul exécutable est une fonction de Bun, et le mode multi-cœur décrit dans la documentation de déploiement repose sur SO_REUSEPORT, qui ne fonctionne que sous Linux et que sous Bun. En dehors de Bun, tu obtiens un framework qui fonctionne, moins une partie de ce qui te l'avait fait choisir. Si ta plateforme de déploiement n'a pas d'image Bun, ou si l'équipe refuse d'ajouter un second runtime à côté de Node, cela tranche la question plutôt que d'être un détail.
Les documents du projet citent un chiffre de dix-huit fois plus rapide qu'Express, d'après la suite TechEmpower. Ce fragment du README est commenté à l'intérieur du paquet publié, et tout chiffre de ce genre vient d'un test synthétique où le transport domine le temps de requête plutôt que le code applicatif. Dans un service qui interroge une base de données, l'écart entre frameworks disparaît généralement dans le bruit.
Elysia face aux alternatives
| Caractéristique | Elysia | Hono | tRPC | Fastify |
|---|---|---|---|---|
| Runtime par défaut | Bun | tout ce qui respecte Web Standard | une couche au-dessus d'un framework | Node |
| Types côté client | Eden treaty | le client hc | le cœur de la bibliothèque | aucun |
| Protocole | HTTP simple et OpenAPI | HTTP simple | format propre sur HTTP | HTTP simple |
| Validation | TypeBox via l'export t | au choix, via des middlewares | au choix, par exemple Zod | JSON Schema via Ajv |
| Version actuelle | 1.4.29 | 4.13.3 | 11.18.0 | 5.12.1 |
| Licence | MIT | MIT | MIT | MIT |
Le choix se règle en trois questions. Si tu es déjà sur Bun et que tu écris une interface de programmation consommée par ton propre front-end TypeScript, Elysia offre le chemin le plus court d'une route à un appel navigateur. Si tu dois déployer sur plusieurs plateformes ou en edge, Hono fait la même chose pour les types via son client hc tout en fonctionnant partout où Web Standard fonctionne. Si le client et le serveur vivent dans un seul dépôt et que personne en dehors de l'équipe n'appellera ces routes, tRPC reste l'option la plus soignée, même si tu la paies par un protocole propre.
Erreurs courantes
La première est de casser la chaîne en instructions séparées. Écrire app.get(...) sur sa propre ligne sans réaffecter le résultat s'exécute correctement à l'exécution mais n'ajoute aucune route au type de l'instance. L'effet est trompeur : le serveur répond alors qu'Eden prétend que le chemin n'existe pas. La chaîne doit rester une seule expression, ou le résultat doit être réaffecté.
La deuxième est de mélanger les scopes @elysia/ et @elysiajs/ dans un même projet. Les deux versions d'un paquet peuvent atterrir ensemble dans node_modules, et tu obtiens alors deux modules distincts portant les mêmes noms de types et des erreurs de compilation dont le texte ne pointe nulle part près de la cause. Choisis un scope et tiens-t'y dans tout le dépôt.
La troisième est de copier des exemples du README du paquet Eden publié. Il contient la fonction edenTreaty de première génération et une enveloppe schema sur les définitions de routes que la version actuelle n'accepte pas. Les exemples actuels se trouvent dans la documentation du site du projet, pas dans le paquet.
La quatrième est d'omettre le schéma de réponse. Sans champ response, Elysia renvoie tout ce que produit le handler, y compris chaque colonne tirée de la base de données. Un schéma de réponse combiné à normalize réglé sur exactMirror retire les champs en trop et décrit en même temps le contrat dans le document OpenAPI.
La cinquième est de traiter les paramètres de requête comme des nombres. Tout ce qui arrive dans une URL est du texte. Un schéma t.Number() rejette la valeur "2", alors que t.Numeric() la convertit avant l'exécution du handler. Le même piège s'applique aux paramètres de chemin.
La sixième est de supposer qu'un plugin écrit pour Bun fonctionnera une fois l'adaptateur Node attaché. L'adaptateur traduit la couche serveur, pas chaque appel d'API Bun fait à l'intérieur d'un plugin. En exécutant sous Node, chaque plugin doit être vérifié individuellement.
La septième est une seule instance géante qui contient plusieurs centaines de routes. Le compilateur TypeScript doit maintenir un seul type décrivant le tout, et le temps de complétion dans l'éditeur augmente avec lui. Découper en modules de domaine reliés par .use() résout le problème avant qu'il n'apparaisse.
FAQ
Elysia fonctionne-t-il sur Node ?
Oui, via un adaptateur installé séparément et passé au constructeur sous la forme new Elysia({ adapter: node() }). L'adaptateur repose sur les paquets srvx et crossws. Le framework lui-même ne déclare aucun champ engines, donc un gestionnaire de paquets ne bloquera pas l'installation sous Node. En dehors de Bun, tu perds la compilation en exécutable et certains plugins qui s'appuient sur des API de Bun.
En quoi Eden diffère-t-il de tRPC ?
Par la profondeur à laquelle il touche au protocole. tRPC définit son propre format d'appel et exige son propre client. Elysia expose des routes HTTP ordinaires, avec Eden comme surcouche facultative pour les clients TypeScript. Une route peut être appelée depuis curl ou depuis un service dans un autre langage, et le plugin OpenAPI génère un document pour elle.
Depuis quel scope npm installer les plugins ?
La documentation du projet demande d'installer depuis le scope @elysia/, et les versions y sont plus récentes : l'adaptateur Node affiche 1.4.6 contre 1.4.5 dans le scope @elysiajs/, et Eden 1.4.10 contre 1.4.9. L'ancien scope compte bien plus de versions derrière lui et est toujours maintenu par la même personne. Mélanger les deux dans un même projet finit en conflit de types.
Elysia est-il prêt pour la production ?
La ligne 1.4 est stable et largement utilisée, mais la dernière version stable date du 16 juin 2026, tandis que le travail s'oriente vers la version deux, publiée en bêta depuis août 2026. Le dépôt compte environ 18,9 mille étoiles, 568 forks et 373 issues ouvertes. Quand tu planifies un déploiement, tiens compte d'une migration future.
Elysia coûte-t-il quelque chose ?
Non. Tout le projet est sous licence MIT, sans variante payante et sans restriction d'usage commercial. Le financement passe par GitHub Sponsors, et l'auteur est en pratique une seule personne, ce qui se traduit par l'absence de contrat de support et un développement lié à sa disponibilité.
La documentation se trouve sur le site du projet, le client est décrit dans la section Eden, et le code source dans le dépôt GitHub.