# @azerothjs/http
**AzerothJS server kernel - web-standard Request/Response HTTP stack (no third-party dependencies) where every request is a reactive root**
[](https://www.npmjs.com/package/@azerothjs/http)
[](https://github.com/AzerothJS/AzerothJS/blob/main/LICENSE)
[](https://nodejs.org)
---
Part of [AzerothJS](https://github.com/AzerothJS/AzerothJS) - the fine-grained fullstack framework. This is the server half: a web-standard HTTP stack for Node >= 22, written from scratch with no third-party dependencies (it builds only on sibling `@azerothjs/*` packages - the reactive request root, schema validation, and the logger).
---
## Install
> [!NOTE]
> ESM-only, Node >= 22. `azerothjs` is a REQUIRED peer: the kernel wires per-request
> reactive-root isolation into the `azerothjs` runtime, and both halves must share one copy of
> it, so it is installed alongside rather than bundled.
```sh
npm install @azerothjs/http azerothjs
```
---
## Overview
Handlers are `(context) => Response` on WHATWG types - one context carries the request, params, URL, and middleware additions. Node's `http`/`http2`
appear only in edge adapters, which buys three things at once: the same app serves on any
fetch-shaped runtime through [`toFetchHandler`](#-other-runtimes---bun-deno-workers-vercel-edge),
`app.handle(new Request(...))` is the entire integration-testing story
(no sockets, no inject shim), and "headers already sent" or double-send are unrepresentable -
a handler returns exactly one `Response`.
> `app.handle` itself returns the kernel's fast internal response, not a host-constructed
> `Response`. It is the right thing to call in a test; a non-Node runtime needs
> `toFetchHandler(app)`, which is one line. See the runtimes section below.
```ts
import { App, json, readJson } from '@azerothjs/http';
import { serve } from '@azerothjs/http/node';
const app = new App();
// One `context` per handler: the request, the params (typed from the pattern), the
// URL, and whatever middleware added. Return a Response - never mutate an argument.
app.get('/users/:id', (context) => json({ id: context.params.id }));
app.post('/users', async ({ request }) =>
{
const body = await readJson<{ name: string }>(request); // limits ON; bad input -> 400/413/415
return json({ created: body.name }, { status: 201 });
});
const served = await serve(app, { port: 3000 });
// served.shutdown(): graceful - drain in-flight responses up to the grace period, destroy
// what remains (held WebSockets exit in milliseconds, not after the grace), then close.
```
Scaffold a complete runnable server like this - a custom error envelope, a scoped `with`
guard, and graceful shutdown, in one file with no build step - with
`npm create azeroth@latest` (the backend template).
---
## Development
There is no build step in the dev loop. Node >= 22 runs TypeScript directly, so
the whole story is one command:
```sh
node --watch src/main.ts # runs the server, restarts on any change it imports
```
Wire it as your `dev` script and that is the entire setup - no bundler, no
`tsc -w` in a second terminal. The dev *run* pulls in nothing; the only dev
dependencies are the two the type-check gate needs (`typescript` for `tsc`, and
`@types/node` so `tsc` can resolve the `node:http` types this package's adapters
reference):
```jsonc
// package.json
{
"type": "module",
"scripts": {
"dev": "node --watch src/main.ts",
"start": "node src/main.ts",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"typescript": "^5.7.0",
"@types/node": "^24.0.0"
}
}
```
Node's native TypeScript is *strip-only*: it erases types and runs, it does not
check them. So type errors never block `node --watch` (you keep moving), and
`tsc --noEmit` stays a separate gate you run in CI or on save. A minimal
`tsconfig.json` for that gate, matching the `.ts` import extensions Node wants -
`types: ["node"]` is what silences the `Cannot find name 'node:http'` errors from
the adapter typings:
```jsonc
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"allowImportingTsExtensions": true,
"noEmit": true,
"strict": true,
"types": ["node"]
}
}
```
Relative imports carry the `.ts` extension (`import { x } from './x.ts'`) - that
is what Node resolves at runtime, and the tsconfig above lets `tsc` accept it too.
**When you do need a build step:** only if something in your stack relies on
`emitDecoratorMetadata` - a decorator-driven ORM (TypeORM, etc.) reads type
metadata that strip-only execution does not emit. Then compile with `tsc` and run
`node --watch dist/main.js`. A plain `@azerothjs/http` app needs none of that.
---
## The typed API layer - `@azerothjs/http/api`
The typed API system lives in this package as the `./api` subpath: declare each
feature once with `feature()` - routes, schemas, guards, handlers, docs, colocated,
with `routes.form`/`routes.raw`/`routes.stream` making uploads, webhooks and SSE first-class -
`register` it (boundary validation, the typed reply channel), export OpenAPI from
the same declaration, and consume it in the browser through the fully inferred
client at `@azerothjs/http/api/shared` (`typeof` the server's features plus a
two-fields-per-route manifest; client-safe: it never drags server code into a
bundle). The full guide: [docs/api.md](./docs/api.md).
---
## Calling your own api in process
A page rendered on the server often needs what its own api already serves. That call does not
have to go out to a socket and back: when the render is answering a request that carries the
api, the same typed client dispatches through `app.handle` in process, with the visitor's
identity and none of the round trip.
```ts
// the same module the browser imports
export const client = createClient