KoalaTS
Build controller-based Node.js backends with less ceremony
KoalaTS 1.x gives you an opinionated starting point for controllers, routes, requests, responses, and application configuration without forcing you to assemble the stack from scratch.
Why teams reach for it
KoalaTS 1.x gives backend projects a clear starting point: controller methods define routes, the request scope exposes transport data, and configuration stays predictable across environments.
- Explicit controller registration and routing
- Practical defaults instead of repeated framework assembly
- Patterns that stay readable as features and teams grow
Problem
Node backends don’t scale well by default
- Projects become messy as they grow.
- Teams drift because there is no shared structure.
- Every new service starts with another round of library decisions.
- Configuration and request flow get duplicated across projects.
Most Node backends work at first, then accumulate ad hoc structure. Each team solves routing, validation, state, and boundaries a little differently, which makes the code harder to reason about over time.
Idea
A structured way to build backends
KoalaTS gives you a stable baseline built around explicit routes, middleware, request and response primitives, and predictable application structure. You spend less time inventing conventions and more time building backend behavior.
- Controllers keep HTTP entry points explicit.
- Decorators describe routes where the behavior lives.
- Request and response handling stay easy to read.
- Configuration remains predictable across environments.
What You Get
The pieces you need to keep moving
Controller-driven routing
Define routes directly on controller methods with decorators and register controllers explicitly in your application configuration.
Practical request handling
Use the request scope to access params, query values, body data, files, and headers without inventing your own transport conventions.
Consistent structure
Keep the same controller, routing, and configuration patterns across services so teams can read and extend code without re-learning the project shape.
Explicit responses
Control status codes, body payloads, and headers through the response object in one predictable place.
Examples
A framework shape you can read quickly
KoalaTS 1.x keeps the surface area small: define routes on controllers and manage runtime configuration with familiar environment files.
export class HomeController {
@Route({method: 'GET', path: '/'})
index(scope: IScope): void {
scope.response.body = {ok: true};
}
}
Architecture
Designed with architecture in mind
KoalaTS is influenced by the same ideas that make larger systems maintainable: clear boundaries, explicit dependencies, and a separation between transport concerns and application behavior.
- Controllers keep HTTP handling explicit without hiding behavior.
- Configuration remains readable through layered environment files.
- Code stays easier to discuss, review, and evolve as a system.
Application shape
Controllers define HTTP entry points, route decorators keep behavior discoverable, and the HTTP scope keeps request and response data explicit.
Why it matters
That structure reduces accidental coupling and makes it easier to reason about behavior as the codebase and team both grow.
Getting Started
Start small and keep the structure
Create the project
Generate a new application with `npx @koala-ts/cli create my-app` and start from the default structure.
Configure and run
Set environment values, install dependencies, and start the generated application with the provided scripts.
Add your first endpoint
Add a controller method with `@Route`, register the controller in `config/app.ts`, and build from the request and response basics.
Start building structured backends today
Start with the documentation when you want the full model, or jump into configuration and build your first structured endpoint with the documented `1.x` patterns.