@gratisnation/cf-kit

An opinionated toolkit for Cloudflare Workers — a thin, composable layer on top of Hono + Drizzle. Stops the copy-paste between Workers projects. Not a framework (Hono is). Not an auth provider (it's a toolkit). Zero runtime deps of its own; everything heavy is a peer dependency.

0.x — the API is still evolving and may change between minor versions.

Install

npm i @gratisnation/cf-kit hono
# per-module peers, as needed:
#   /db   -> drizzle-orm
#   /auth -> jose zod
#   types -> @cloudflare/workers-types

Ships compiled ESM + type declarations; your Worker bundler (wrangler/esbuild) takes it from there.

Quick start

import { createApp, NotFound } from '@gratisnation/cf-kit'

const app = createApp<Env>({ cors: true })

app.get('/users/:id', async (c) => {
  const user = await load(c.req.param('id'))
  if (!user) throw new NotFound('user')   // -> 404 { error: { code: 'not_found', message } }
  return c.json(user)                       // -> 200 { ... }  (success is plain; only errors are shaped)
})

export default app

Entry points

Import	Module
`@gratisnation/cf-kit`	core: `createApp`, `HttpError`s, `defineEnv`, `validate`, `idempotent`, logger
`@gratisnation/cf-kit/db`	D1 + Drizzle: `createDb`, `scope`, column / query / pagination helpers
`@gratisnation/cf-kit/do`	Durable Objects (plain): `durableDb`, `Scheduler`, `RealtimeDO`, `RateLimiterDO`, `StorageDO`, `scopedDO`
`@gratisnation/cf-kit/auth`	`createAuth` (jwt / apiKey / session), guards, tokens, OAuth, passwords, `Storage`, rate limit
`@gratisnation/cf-kit/cache`	`createCache` — KV cache-aside with SWR + single-flight
`@gratisnation/cf-kit/r2`	`createR2` (serve / put / list) + `presigner`
`@gratisnation/cf-kit/queue`	`createConsumer` / `createProducer`, per-message ack, backoff

Full guides per module live in docs/.

Responses

Success is whatever you return (c.json(data) — no envelope). Errors get one uniform shape via the global handler, so clients branch on the HTTP status + a stable error.code:

{ "error": { "code": "not_found", "message": "user not found",
             "details": [ /* diagnostics */ ], "params": { /* i18n interpolation */ } } }

Develop

pnpm install
pnpm typecheck
CLOUDFLARE_DISABLE_SANDBOX=1 pnpm test   # vitest in real workerd (D1/DO/KV/R2 bindings)
pnpm build                                # tsup -> dist/ (ESM + .d.ts)

Local iteration from a consuming project: "pnpm": { "overrides": { "@gratisnation/cf-kit": "link:../cf-kit" } }.

JSPM