Installation

Install the package

Stoma requires Hono v4.x or later as a peer dependency. Install both together:

npm

npm install @homegrower-club/stoma hono

yarn

yarn add @homegrower-club/stoma hono

pnpm

pnpm add @homegrower-club/stoma hono

Optional dependencies

Package	Version	Purpose
hono	>=4.0	Required peer dependency. Provides the router, context, and middleware system.
zod	>=3.0	Optional. Enables config schema validation at construction time.

If you want Zod-based config validation:

npm

npm install zod

yarn

yarn add zod

pnpm

pnpm add zod

TypeScript configuration

Stoma is written in TypeScript and exports raw .ts source files directly — there is no build step. Your bundler (Vite, esbuild, wrangler) compiles the TypeScript at build time alongside your own code.

Your tsconfig.json should use these settings at minimum:

{
  "compilerOptions": {
    // Target ES2022 or later - Stoma uses modern APIs:
    // - structuredClone() for cloning request/response objects
    // - AbortSignal.timeout() for timeout handling
    // - crypto.subtle for JWT signing/verification
    // All available in Cloudflare Workers, Deno, Bun, Node 20+
    "target": "ES2022",

    // Use ESNext modules (modern JavaScript module system)
    // This matches how bundlers like Vite, esbuild, and wrangler work
    "module": "ESNext",

    // Required for subpath exports to resolve correctly
    // Allows @homegrower-club/stoma/policies, @homegrower-club/stoma/config, etc.
    "moduleResolution": "bundler",

    // Enable all strict type checking
    // Stoma's types are authored with strict mode - you'll get the best experience
    "strict": true,

    // Interop with CommonJS modules (some dependencies may use CommonJS)
    "esModuleInterop": true,

    // Skip type checking of declaration files (reduces build time)
    // You can set to false if you need perfect type coverage
    "skipLibCheck": true
  }
}

Key requirements:

• target: "ES2022" or later. Stoma uses structuredClone, AbortSignal.timeout, crypto.subtle, and other modern APIs. These are available natively in Cloudflare Workers, Deno, Bun, and Node.js 20+.
• moduleResolution: "bundler". Required for subpath exports (@homegrower-club/stoma/policies, @homegrower-club/stoma/config) to resolve correctly.
• strict: true. Recommended. Stoma’s types are authored with strict mode enabled.

Subpath exports

The package exposes five entry points:

Import path	Contents
@homegrower-club/stoma	Main entry: createGateway, all built-in policies, SDK helpers, all types
@homegrower-club/stoma/policies	Policy factory functions, SDK helpers, and policy types only
@homegrower-club/stoma/config	Config type re-exports + Zod validation schemas (validateConfig, safeValidateConfig, GatewayConfigSchema)
@homegrower-club/stoma/sdk	Policy SDK: definePolicy(), createPolicyTestHarness(), Priority constants, resolveConfig, policyDebug, withSkip
@homegrower-club/stoma/adapters	Cloudflare-specific adapters (KV, Durable Objects)

For most use cases, import everything from the main entry point:

// The main entry point includes everything you need for most use cases:
// - createGateway: The core function to build your gateway
// - All built-in policies: jwtAuth, rateLimit, cors, requestLog, etc.
// - SDK helpers: definePolicy, Priority, withSkip, etc.
// - All types: GatewayConfig, RouteConfig, PolicyContext, etc.
import { createGateway, jwtAuth, rateLimit, cors } from "@homegrower-club/stoma";

For custom policy development, import the SDK directly:

// The SDK provides building blocks for authoring custom policies:
/*
  definePolicy: Creates a policy factory function with defaults, priority, etc.
  Priority: Named constants for policy execution order (Priority.AUTH, Priority.CACHE, etc.)
  createPolicyTestHarness: Test your policy in isolation without a full gateway
  resolveConfig: Deep-merge default config with user overrides
  policyDebug: Namespaced debug logger with zero overhead when disabled
  withSkip: Conditionally disable a policy based on request characteristics
*/
import { definePolicy, Priority, createPolicyTestHarness } from "@homegrower-club/stoma/sdk";

Runtime-specific setup

Stoma runs on any JavaScript runtime that supports Web Standard APIs. The core library has no runtime-specific dependencies. Additional setup depends on where you deploy.

Cloudflare Workers

Install the Workers type definitions as a dev dependency:

npm install -D @cloudflare/workers-types

Add them to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@cloudflare/workers-types"]
  }
}

This enables typed access to c.env bindings (secrets, Service Bindings, KV namespaces). The @homegrower-club/stoma/adapters subpath export provides Cloudflare-specific stores for rate limiting (KV, Durable Objects) and circuit breakers.

Node.js

Install the Hono Node.js adapter:

npm install @hono/node-server

Then serve the gateway app:

import { serve } from "@hono/node-server";
serve({ fetch: gateway.app.fetch, port: 3000 });

Deno and Bun

No additional dependencies are needed. Export or serve the gateway.app directly using the runtime’s native APIs. See the Quick Start for examples.

Next steps

With the package installed, proceed to the Quick Start to define your first gateway.