diff --git a/components/mdx.tsx b/components/mdx.tsx index 891dff3..262f11a 100644 --- a/components/mdx.tsx +++ b/components/mdx.tsx @@ -1,6 +1,6 @@ // Components the MDX pages may use besides the Fumadocs ones. import type { ReactNode } from "react"; -import { run, scenarios, servers } from "@/data/bench"; +import { run, scenarios, servers, widerRun } from "@/data/bench"; /** * Two code blocks next to each other on a wide screen, one under the other on a narrow one: @@ -12,9 +12,14 @@ export function Side({ children }: { children: ReactNode }) { const REPORTS = "https://github.com/inkanjs/inkan/tree/main/bench/reports"; -/** The numbers of data/bench.ts for the servers named, so the page never drifts from /benchmarks. */ -export function BenchTable({ names }: { names: string[] }) { - const rows = names.map((name) => servers.find((s) => s.name === name)).filter((s) => s !== undefined); +/** + * The numbers of data/bench.ts for the servers named, so the page never drifts from /benchmarks. + * `wide` takes them from the run with every framework instead of the release bench. + */ +export function BenchTable({ names, wide = false }: { names: string[]; wide?: boolean }) { + const from = wide ? widerRun.servers : servers; + const meta = wide ? widerRun.run : run; + const rows = names.map((name) => from.find((s) => s.name === name)).filter((s) => s !== undefined); return ( <>
@@ -46,9 +51,19 @@ export function BenchTable({ names }: { names: string[] }) {

- Requests per second next to bare node:http as 100, on Node {run.node}, a {run.machine}, {run.tool},{" "} - {run.rounds} rounds of {run.seconds} seconds, measured {run.date}. The full runs, with the method and the raw numbers, are - in bench/reports; every scenario is on /benchmarks. + Requests per second next to bare node:http as 100, on Node {meta.node}, a {meta.machine}, {meta.tool},{" "} + {meta.rounds} rounds of {meta.seconds} seconds, measured {meta.date} + {wide ? ", all ten in one run" : ""}. The full runs, with the method and the raw numbers, are in{" "} + bench/reports + {wide ? ( + <> + ; this one is frameworks-2026-11.md. + + ) : ( + <> + ; every scenario is on /benchmarks. + + )}

); diff --git a/content/docs/compare.mdx b/content/docs/compare.mdx index eb047d8..2d49289 100644 --- a/content/docs/compare.mdx +++ b/content/docs/compare.mdx @@ -1,10 +1,10 @@ --- -title: "inkan, Express, Fastify, Hono" -description: "What each of the four is best at, when I would pick which, and how fast they are on the same bench." +title: "inkan next to the other Node frameworks" +description: "Express, Fastify, Hono, Koa, hapi, h3, Elysia and NestJS: what each is best at, when I would pick which, and how fast they are on the same bench." --- I write inkan, so take this page with that in mind. I have tried to put down where each of -the other three is the better choice, because for a lot of projects one of them is. If +the others is the better choice, because for a lot of projects one of them is. If something here is wrong or out of date, [open an issue](https://github.com/inkanjs/inkan/issues) and I will fix the page. @@ -18,7 +18,7 @@ a rejected promise from an async handler to the error middleware, so the oldest What it leaves to you is everything about the shape of the data. Validation, the types of `req.body`, an OpenAPI document and the docs are separate tools (zod or express-validator, swagger-jsdoc or a hand-written spec), and nothing makes them agree with the handler. It is -also the slowest of the four by a wide margin on the bench below, mostly in routing: with 400 +also the slowest of Express, Fastify, Hono and inkan by a wide margin on the bench below, mostly in routing: with 400 routes or a 404 it does about a fifth of what bare `node:http` does. **Pick Express when** the team knows it well, you depend on middleware that only exists for @@ -58,6 +58,72 @@ is at home, and these numbers say nothing about that. **Pick Hono when** your API runs at the edge or on Workers, or cold start and bundle size matter more to you than anything on this page. +## Koa + +Koa is Express done again by the same people, around `async`/`await`: one context object +instead of a request and a response, and middleware that wraps the rest of the chain, so it +can act both before and after the handler. The core is tiny and leaves almost everything to +packages: routing (`@koa/router`), body parsing, validation. Code written for it tends to be +clean and easy to follow. + +On the bench below it comes last, and that needs a word. `@koa/router` tests each request +against every route, and the bench app has 800 of them. With two routes Koa is level with +Express. So the number is fair for a big Koa app on the standard router, not for Koa itself. + +**Pick Koa when** you like the onion model of middleware, your app has tens of routes rather +than hundreds, and you want to choose every piece yourself. + +## hapi + +hapi is built for large teams and long-lived services. Routes are configuration objects +with validation (Joi), auth strategies, caching and lifecycle extensions next to the handler, +and plugins have explicit dependencies and their own config. It came out of Walmart, where it +carried Black Friday traffic, and it puts a lot of care into security defaults. + +It is more ceremony than the others for a small API, and its ecosystem is mostly its own +(`@hapi/*`) rather than the wider middleware world. On the bench it is a little ahead of +Express overall, and clearly ahead on routing. + +**Pick hapi when** a large team needs strong conventions, auth and validation configured per +route, and you value stable, careful releases over speed. + +## h3 + +h3 is the server under Nitro and Nuxt. Like Hono it is built on web-standard requests and +responses and runs on Node, Bun, Deno, Workers and more, with small composable helpers +(`readBody`, `getQuery`) instead of a big framework object. On the bench it is the fastest of +the newcomers and not far behind Hono, strong on large bodies and answers. + +**Pick h3 when** you are in the Nuxt or Nitro world, or want a small, standards-based server +that runs on several runtimes, and you bring your own validation and docs. + +## Elysia + +Elysia is made for Bun, and its idea is close to inkan's: a schema per route (TypeBox) gives +validation, the handler's types, an OpenAPI document and an end-to-end typed client (Eden). +It is fast and pleasant to write, and on Bun it is among the fastest servers in JavaScript. + +On Node it runs through `@elysiajs/node`, and the bench only measures that. It does well on +answers without input, and loses about half wherever its schemas read params or a body, +because each request first goes through the adapter. Measure it on Bun before you judge it. + +**Pick Elysia when** you run on Bun and want contracts, types and a typed client from one +place. On Node, inkan or Fastify give you the same idea for less. + +## NestJS + +NestJS is a full application framework: modules, dependency injection, decorators, +guards, pipes and interceptors, in the style of Angular or Spring. It brings an answer for +almost everything (OpenAPI, GraphQL, queues, microservices, testing) and a structure that +many developers already know, which is a lot when a big team builds a big app. + +It sits on Express or Fastify and adds its own layer, so it is never faster than the one +beneath it. On its default Express platform it lands a little below Express on the bench. +Validation is usually `class-validator`, which the bench does not use; there it checks by hand. + +**Pick NestJS when** the app is large, the team wants one structure and DI everywhere, and +the speed of a single request matters less than how the codebase holds together. + ## inkan inkan starts from one contract per route: params, query, headers, body, the answers per @@ -90,6 +156,14 @@ schema check does not have to cost much: the two frameworks that validate everyt two fastest. It measures one small route at a time on one machine; your database will usually matter more than any of these differences. +All ten in one run, Koa, hapi, h3, Elysia and NestJS next to the ones above (Elysia checks +with its own schemas, the other four by hand): + + + +This is one run, not the median of three, so inkan and Fastify only differ by noise here; +the table above is the steadier one for them. Elysia is measured on Node, not on Bun. + ## Moving over If you have an app on one of the others, [from Express](/docs/migrate/express) and diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 3c6b4ed..c73e59b 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -79,7 +79,7 @@ server to what its docs say. | Runtime dependencies | several | several | none | **none** | That table is about features. Where each of the others is the better choice, and the -benchmark numbers next to each other, are in [inkan, Express, Fastify, Hono](/docs/compare). +benchmark numbers next to each other, are in [inkan next to the other Node frameworks](/docs/compare). Coming from one of them: [from Express](/docs/migrate/express), [from Fastify](/docs/migrate/fastify). diff --git a/data/bench.ts b/data/bench.ts index 3b79841..14398d3 100644 --- a/data/bench.ts +++ b/data/bench.ts @@ -47,3 +47,21 @@ export const servers: Server[] = [ { name: "Hono", what: "checks by hand", score: 85.6, values: { hello: 94, params: 77, body: 93, answer: 98, router: 77, notFound: 85, invalid: 87 } }, { name: "Express", what: "checks by hand", score: 48.9, values: { hello: 53, params: 52, body: 69, answer: 73, router: 23, notFound: 23, invalid: 53 } }, ]; + +// One run with ten frameworks at once (bench/reports/frameworks-2026-11.md). Only the compare +// page shows it, next to the release numbers above, never mixed into them. +export const widerRun: { run: typeof run; servers: Server[] } = { + run: { ...run, date: "2026-11-13" }, + servers: [ + { name: "node:http, by hand", what: "the baseline", base: true, score: 100, values: { hello: 100, params: 100, body: 100, answer: 100, router: 100, notFound: 100, invalid: 100 } }, + { name: "Fastify", what: "schemas, like inkan", score: 88.8, values: { hello: 88, params: 96, body: 95, answer: 80, router: 91, notFound: 83, invalid: 73 } }, + { name: "inkan", what: "on node:http", ours: true, score: 88.5, values: { hello: 89, params: 90, body: 89, answer: 88, router: 93, notFound: 88, invalid: 78 } }, + { name: "Hono", what: "checks by hand", score: 81.0, values: { hello: 85, params: 71, body: 88, answer: 97, router: 72, notFound: 71, invalid: 84 } }, + { name: "h3", what: "checks by hand", score: 75.8, values: { hello: 75, params: 72, body: 88, answer: 95, router: 72, notFound: 60, invalid: 80 } }, + { name: "Elysia", what: "on Node, its own schemas", score: 54.7, values: { hello: 76, params: 39, body: 41, answer: 93, router: 43, notFound: 59, invalid: 22 } }, + { name: "hapi", what: "checks by hand", score: 46.5, values: { hello: 45, params: 40, body: 52, answer: 76, router: 44, notFound: 45, invalid: 38 } }, + { name: "Express", what: "checks by hand", score: 40.1, values: { hello: 43, params: 39, body: 59, answer: 68, router: 18, notFound: 16, invalid: 43 } }, + { name: "NestJS", what: "on Express", score: 34.4, values: { hello: 36, params: 34, body: 54, answer: 63, router: 17, notFound: 14, invalid: 30 } }, + { name: "Koa", what: "with @koa/router", score: 25.2, values: { hello: 20, params: 20, body: 38, answer: 51, router: 22, notFound: 20, invalid: 24 } }, + ], +};