GETTING STARTED

Welcome to Futon

Futon is the WinterCG-compatible HTTP engine at the foundation of the Rasengan backend stack. It gives you a router, a middleware pipeline, and request/response helpers built entirely on Web API primitives. No Node-specific types leak into your route handlers.

What is Futon?

Futon is a zero-dependency library built on Request, Response, Headers, and URL, the same primitives every modern JavaScript runtime understands. That means the exact same route handler runs unchanged on Node, Bun, Deno, or Cloudflare Workers.

You can use Futon directly as a lightweight standalone HTTP library, or through @rasenganjs/server, which builds controllers, dependency injection, and WebSockets on top of it.

Key Features

FeatureDescription
Radix-tree RouterO(k) route matching regardless of how many routes you register.
Onion-model MiddlewareKoa-style (ctx, next) composition, the same pattern used by Express and Koa.
WinterCG AdaptersShip the same handler to Node, Bun, Deno, or Workers via toWinterCgHandler() or toExpressHandler().
File UploadsMulter-style fileUpload() middleware with pluggable storage engines.
Lifecycle HooksObserve beforeRequest, afterResponse, and onError without adding middleware.
Typed ContextA single ctx object carries the request, params, query, and a chainable response builder.

A Minimal Example

server.ts
import { Futon, json, logger, cors } from '@rasenganjs/futon';
 
const app = new Futon();
 
app.use(logger());
app.use(cors());
 
app.get('/api/health', async () => json({ status: 'ok' }));
 
app.onError(async (error, ctx) => {
  console.error(error);
  return json({ error: error.message }, { status: 500 });
});
 
export default app;

Futon itself never opens a port. That's the job of a runtime adapter (see Runtime Adapters). Futon only knows how to turn a Request into a Response.

How This Documentation Is Organized

  • Getting Started: install Futon and run your first handler.
  • Core Concepts: routing, context, middleware, file uploads, hooks, and adapters.
  • API Reference: the full exported surface of @rasenganjs/futon.

If you're building a full backend application with controllers and dependency injection, you'll likely want @rasenganjs/server instead, which uses Futon under the hood.

Join Our Community

Need help? Connect with other developers:

Let's build something amazing with Rasengan.js! 🚀