@rdlabo/workers-hono-kit

Shared Hono building blocks for Cloudflare Workers APIs: weak ETags, NestJS-shaped validation and error bodies, Firebase auth middleware, AWS helpers, AI Gateway wiring, Stripe, KV, queues, realtime, and offline contracts.

Try a Hono API locally: send a health request, inspect its weak ETag, and see the missing-route JSON response. No Cloudflare account or open port is needed for the first exercise.

Install

npm install @rdlabo/workers-hono-kit

The package is ESM with TypeScript declarations and requires Node.js 20 or later for tooling. Stripe is included directly. npm installs the required Hono, validation, authentication, AWS, and AI Gateway peers; package managers configured not to install peers automatically must add them explicitly:

npm install hono zod @hono/zod-validator jose aws4fetch ai-gateway-provider

Additional optional peers and packages stay separate:

| Capability | Install | | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | | AI SDK model wrappers | ai | | MySQL and Hyperdrive | @rdlabo/workers-mysql and optionally drizzle-orm | | IANA timezone utilities | @rdlabo/workers-timezone |

From 0.12.0, /testing retains static DB compatibility exports. Every /testing consumer, including applications using only Firebase or KV fakes, must install @rdlabo/workers-mysql and drizzle-orm.

Version 0.12.0 moves the root MySQL exports to the standalone package and /mysql adapter. Existing users should follow the MySQL migration guide before upgrading.

Quick start

A minimal Hono app with weak ETags, the shared error body, and 404 JSON { message: 'Cannot METHOD path', error: 'Not Found', statusCode: 404 }:

import { Hono } from 'hono';
import { createAppErrorHandler, finalizeResponse, notFoundHandler } from '@rdlabo/workers-hono-kit';

const app = new Hono();

app.use('*', finalizeResponse());
app.onError(createAppErrorHandler());
app.notFound(notFoundHandler);

app.get('/health', (c) => c.json({ ok: true }));

export default app;

Choose an entry point

| Import | Responsibility | | ---------------------------------------- | -------------------------------------------------------------------- | | @rdlabo/workers-hono-kit | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives | | @rdlabo/workers-hono-kit/mysql | Hono container adapter for @rdlabo/workers-mysql | | @rdlabo/workers-hono-kit/offline | Offline replica wire, cursor, journal, and compatibility contracts | | @rdlabo/workers-hono-kit/realtime | Durable Object WebSocket and retry helpers | | @rdlabo/workers-hono-kit/testing | Auth helpers, fakes, Stripe fixtures, and compatibility test exports | | @rdlabo/workers-hono-kit/db | Deprecated compatibility path for @rdlabo/workers-mysql | | @rdlabo/workers-hono-kit/business-time | Deprecated compatibility path for @rdlabo/workers-timezone |

The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers install the standalone package, which owns mysql2; Hono-specific wiring stays in the /mysql adapter.

Compatibility import deprecations

Kit /db, /business-time, and the DB-related /testing exports (createTestDb, pool/noop database fakes, and shared Database types) carry symbol-level @deprecated tags that point at @rdlabo/workers-mysql / @rdlabo/workers-timezone. Prefer those packages for new code. The compatibility aliases keep the same runtime identity and signatures; there is no planned removal. Kit-owned helpers such as reopenGuardedPaymentFailedSet, /mysql createContainerRuntime, and Firebase/auth/KV/Stripe test helpers are not deprecated by this migration.

Social auth (Google / Apple)

Root exports verifyGoogleIdentityToken, verifyAppleIdentityToken, hasFirebaseProviderIdentity, and createAppleClientSecret cover reusable OIDC subject verification, Firebase identity matching, and Apple client_secret signing. Applications keep ownership of HTTP responses, persistence, and provider token exchange or revocation.

hasFirebaseProviderIdentity expects a verified Firebase ID-token payload. Pass requireSignInProvider: true when an endpoint requires sign-in through that provider (subject linked and firebase.sign_in_provider matches). Leave it false (default) for link/unlink checks or combined login/link endpoints that also accept sessions established through another provider. This policy belongs to the application.

import { hasFirebaseProviderIdentity, verifyGoogleIdentityToken } from '@rdlabo/workers-hono-kit';

// firebaseVerifier is the application's configured FirebaseVerifier.
const verifiedFirebaseToken = await firebaseVerifier.verifyIdToken(firebaseIdToken);
const subject = await verifyGoogleIdentityToken(googleIdToken, GOOGLE_CLIENT_IDS);
// login: require active Google sign-in
if (!hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject, true)) {
  return c.json({ error: 'Google identity mismatch' }, 401);
}
// link / unlink: subject present is enough
// hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject)

Documentation

• HTTP and Authentication
• Data Layer and MySQL migration
• Realtime and Offline
• Testing and Operations
• Packages and API Reference

Full documentation: https://docs.rdlabo.dev/projects/workers-hono-kit

Candidate artifacts and publication controls are documented in Development.

Maintainers

• rdlabo

License

MIT © rdlabo-dev