rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

What you will build#

This tutorial builds one application, step by step: a notes API with validated input, a real database, authentication, generated OpenAPI docs, and tests. Each page adds one layer and explains the primitive behind it, so by the end you have seen everything the framework can do — and every line came from these pages.

You need Bun ≥ 1.2. Everything runs on Bun's native APIs — Bun.serve — with no adapter layers.

Scaffold the project#

Create the project from the template, a minimal runnable app organized the way NestJS organizes its starter, expressed with Rhythm primitives:

Shell
bunx rhythmx new notes-app
cd notes-app
bun dev   # bun --watch src/main.ts

Four source files carry the whole idea. A service holds business logic, a controller maps routes onto it, a module wires them together, and main.ts serves the module:

Text
src/
  main.ts             Bun.serve over toFetchHandler(appModule)
  app.module.ts       Rhythm app: puts the service in its startup context, mounts the controller
  app.controller.ts   RhythmRouter instance: routes and handlers
  app.service.ts      plain object holding the business logic

The four files#

The service is a plain object — no decorators, no base class. Factories over classes is the convention everywhere:

TypeScript
// src/app.service.ts
export const appService = {
  getHello(): string {
    return "Hello World!";
  },
};

The controller is a RhythmRouter. Its context type declares the dependencies its handlers use — the type-level equivalent of constructor injection:

TypeScript
// src/app.controller.ts
import { RhythmRouter } from "@rhythmjs/router";
import type { RhythmHttpContext } from "@rhythmjs/router/context";
import type { appService } from "./app.service";
import { text } from "@rhythmjs/router/response";

export type AppContext = RhythmHttpContext & {
  appService: typeof appService;
};

export const appController = new RhythmRouter<AppContext>().get("/", (ctx) => {
  text(ctx, ctx.appService.getHello());
});

The module is a Rhythm app. Startup values — built once, before the first request — are added with register(decorate(...)), and the controller is mounted with mount(). Nothing is declared twice: the types of the context grow as you chain:

TypeScript
// src/app.module.ts
import { Rhythm, decorate, mount } from "@rhythmjs/rhythm";
import { appController } from "./app.controller";
import { appService } from "./app.service";

export const appModule = new Rhythm({ name: "app" })
  .register(decorate(() => ({ appService })))
  .use(mount(appController));

And main.ts turns the module into a fetch handler and hands it straight to Bun.serve. Passing the handler itself (not a wrapper) matters: it receives Bun's server on every call and exposes it to handlers as ctx.server, for things like the client address:

TypeScript
// src/main.ts
import { toFetchHandler } from "@rhythmjs/router/fetch";
import { appModule } from "./app.module";

const port = Number(process.env.PORT ?? 3000);

const server = Bun.serve({ port, fetch: toFetchHandler(appModule) });
console.log(`listening on ${server.url}`);

Run and poke it#

Shell
$ bun dev
listening on http://localhost:3000/

$ curl http://localhost:3000/
Hello World!

$ curl -i http://localhost:3000/missing
HTTP/1.1 404 Not Found
Not Found

That is the whole mental model: startup values are added once with decorate(), middleware runs per request in onion order, and the request context carries both through the pipeline. A request no router touches falls out the end as a plain 404. Every page that follows only adds routers, middleware, and startup values to this skeleton. The app stays this small for the first three pages; the modules page then reorganizes it into self-contained feature modules, the layout the rest of the tutorial grows.