GETTING STARTED

Welcome to Rasengan Server

@rasenganjs/server is a production-grade backend framework built on top of Futon. It adds controllers, modules, dependency injection, and schema validation on top of Futon's HTTP engine.

What is Rasengan Server?

If Futon gives you a router and a middleware pipeline, Rasengan Server gives you the structure to organize a real application on top of it: modules that group related controllers and providers, a DI container that wires everything together, and automatic validation for routes with schemas.

main.ts
import { bootstrap } from '@rasenganjs/server';
import appModule from './app.module';
 
bootstrap((app) => {
  app.registerModule(appModule);
});

Key Features

FeatureDescription
ModulesGroup controllers, providers, and middleware under an optional URL prefix, with import/export visibility.
ControllersDeclare related routes as a class, with controller-level middleware and schemas.
Dependency InjectionModule-scoped DI container, constructor injection, lifecycle hooks, circular-dependency detection.
ValidationZod-backed request validation, injected automatically for routes with schemas.
Module PluginsThe extension mechanism that lets @rasenganjs/ws and @rasenganjs/queue add their own defineModule() fields.
WebSocketsLow-level app.websocket() today; NestJS-style Gateways via @rasenganjs/ws.

A Minimal Example

user.controller.ts
import { Controller, type RouteHandler, type Router } from '@rasenganjs/server';
import { UserService } from './user.service';
 
export class UserController extends Controller {
  constructor(private userService: UserService) {
    super();
  }
 
  routes(router: Router) {
    router.get('/', this.findAll);
  }
 
  findAll: RouteHandler = async (ctx) => {
    const users = await this.userService.findAll();
    return ctx.res.json(users);
  };
}
app.module.ts
import { defineModule } from '@rasenganjs/server';
import { UserController } from './user.controller';
import { UserService } from './user.service';
 
export default defineModule({
  prefix: '/users',
  controllers: [UserController],
  providers: [UserService],
});
main.ts
import { bootstrap } from '@rasenganjs/server';
import appModule from './app.module';
 
bootstrap((app) => {
  app.registerModule(appModule);
});

UserController's constructor parameter userService is resolved automatically from the DI container by matching the parameter name against a registered provider, no decorators, no manual wiring.

Built on Futon and Runtime

Rasengan Server depends on @rasenganjs/futon for the HTTP pipeline and @rasenganjs/runtime for the Node/Bun/Workerd adapters. bootstrap() handles both for you. If you only need routing and middleware without controllers/DI/modules, Futon alone may be all you need.

How This Documentation Is Organized

  • Getting Started: install, project structure, and the CLI.
  • Core Concepts: bootstrap, modules, controllers, dependency injection, middleware, validation, file uploads, WebSockets, module plugins, and config/build.
  • Server Ecosystem: the optional packages (@rasenganjs/ws, @rasenganjs/queue, @rasenganjs/validators, @rasenganjs/drizzle) that plug into Rasengan Server via the module plugin system.
  • API Reference: the full exported surface of @rasenganjs/server.