Quick Start

In this guide, we’ll build a production-grade gateway with authentication, rate limiting, and a health check.

Initialize your Gateway Create a new file (e.g., src/index.ts) and use createGateway to define your infrastructure.

import { createGateway, jwtAuth, rateLimit, requestLog, health } from "@homegrower-club/stoma";

const gateway = createGateway({
  name: "my-gateway",
  basePath: "/v1",
  policies: [requestLog()],
  routes: [
    health(),
    {
      path: "/users/*",
      pipeline: {
        policies: [
          jwtAuth({ secret: "env:JWT_SECRET" }),
          rateLimit({ max: 100, windowSeconds: 60 }),
        ],
        upstream: {
          type: "url",
          target: "https://users-api.internal.example.com",
        },
      },
    },
  ],
});

export default gateway.app;

Understand the Core Concepts
- createGateway: The main entry point. It compiles your config into a Hono app.
- basePath: Prefixes all routes (e.g., /v1/users/*).
- Global Policies: policies: [requestLog()] runs on every single request.
- Pipeline: A chain of policies leading to an upstream (where the request ends up).
Choose your Upstream Stoma supports three types of upstreams:
- url: Proxy to any HTTP endpoint (Universal).
- service-binding: Zero-latency Worker-to-Worker routing (Cloudflare only).
- handler: Inline response logic (Universal).
Run and Deploy Since gateway.app is a standard Hono instance, you can run it anywhere.
export default gateway.app;
Run with npx wrangler dev.
import { serve } from "@hono/node-server"; serve({ fetch: gateway.app.fetch, port: 3000 });
// Bun export default gateway.app; // Deno Deno.serve(gateway.app.fetch);

Quick Start

Next Steps