Installation

Install the package

Stoma requires Hono v4.0.0 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.0	Required peer dependency. Provides the router, context, and middleware system.
zod	>=3.0.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",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "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:

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

For custom policy development, import the SDK directly:

import { definePolicy, Priority, createPolicyTestHarness } from "@homegrower-club/stoma/sdk";

Runtime-specific setup

Stoma runs on any runtime Hono supports. 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.