Premiers pas
Briques Hono partagées pour les API Cloudflare Workers : ETags faibles, validation et corps d’erreur au format NestJS, middleware d’authentification Firebase, utilitaires AWS, intégration AI Gateway, Stripe, KV, files de messages, temps réel et contrats hors ligne.
Essayez une API Hono en local : envoyez une requête de vérification de l’état, examinez son ETag faible et observez la réponse JSON à une route inexistante. Ce premier exercice ne nécessite ni compte Cloudflare ni ouverture de port.
Installation
npm install @rdlabo/workers-hono-kit
Le package utilise ESM, fournit des déclarations TypeScript et nécessite Node.js 20 ou version ultérieure pour ses outils. Stripe est inclus directement. npm installe les dépendances pair requises pour Hono, la validation, l’authentification, AWS et AI Gateway ; avec un gestionnaire de packages configuré pour ne pas installer automatiquement ces dépendances, vous devez les ajouter explicitement :
npm install hono zod @hono/zod-validator jose aws4fetch ai-gateway-provider
Les autres dépendances pair et packages facultatifs restent séparés :
| Fonctionnalité | Installation |
|---|---|
| Wrappers de modèles AI SDK | ai |
| MySQL et Hyperdrive | @rdlabo/workers-mysql et, si nécessaire, drizzle-orm |
| Utilitaires de fuseaux horaires IANA | @rdlabo/workers-timezone |
À partir de 0.12.0, /testing conserve des exports statiques de compatibilité pour les bases de données. Tous les utilisateurs de /testing, y compris les applications qui n’utilisent que les doublures Firebase ou KV, doivent installer @rdlabo/workers-mysql et drizzle-orm.
La version 0.12.0 déplace les exports MySQL de la racine vers le package autonome et l’adaptateur /mysql. Les utilisateurs existants doivent suivre le guide de migration MySQL avant la mise à niveau.
Démarrage rapide
Une application Hono minimale avec des ETags faibles, le corps d’erreur partagé et une réponse JSON 404 { 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;
Choisir un point d’entrée
| Import | Rôle |
|---|---|
@rdlabo/workers-hono-kit |
Primitives HTTP, d’authentification, Firebase, AWS, AI, Stripe, KV et de files de messages |
@rdlabo/workers-hono-kit/mysql |
Adaptateur de conteneur Hono pour @rdlabo/workers-mysql |
@rdlabo/workers-hono-kit/offline |
Contrats de format d’échange des répliques hors ligne, de curseurs, de journal et de compatibilité |
@rdlabo/workers-hono-kit/realtime |
Utilitaires WebSocket et de nouvelle tentative pour Durable Objects |
@rdlabo/workers-hono-kit/testing |
Utilitaires d’authentification, doublures, jeux de données de test Stripe et exports de tests de compatibilité |
@rdlabo/workers-hono-kit/db |
Chemin de compatibilité déprécié pour @rdlabo/workers-mysql |
@rdlabo/workers-hono-kit/business-time |
Chemin de compatibilité déprécié pour @rdlabo/workers-timezone |
Le point d’entrée racine ne charge ni MySQL, ni Drizzle, ni les modules de migration réservés à Node. Les utilisateurs de MySQL installent le package autonome, qui prend en charge mysql2 ; l’intégration propre à Hono reste dans l’adaptateur /mysql.
Dépréciation des imports de compatibilité
Les chemins /db, /business-time du kit et les exports de /testing liés aux bases de données (createTestDb, doublures de base de données pool/noop et types Database partagés) portent des balises @deprecated sur chaque symbole, renvoyant à @rdlabo/workers-mysql / @rdlabo/workers-timezone. Privilégiez ces packages pour le nouveau code. Les alias de compatibilité conservent la même identité à l’exécution et les mêmes signatures ; leur suppression n’est pas prévue. Cette migration ne déprécie pas les utilitaires appartenant au kit, tels que reopenGuardedPaymentFailedSet, createContainerRuntime de /mysql et les utilitaires de test Firebase/auth/KV/Stripe.
Authentification sociale (Google / Apple)
Les exports racine verifyGoogleIdentityToken, verifyAppleIdentityToken, hasFirebaseProviderIdentity et createAppleClientSecret fournissent des utilitaires réutilisables pour vérifier le sujet OIDC, le faire correspondre à une identité Firebase et signer le client_secret Apple. Les applications restent responsables des réponses HTTP, de la persistance et de l’échange ou de la révocation des jetons auprès du fournisseur.
hasFirebaseProviderIdentity attend la charge utile d’un jeton d’identification Firebase vérifié. Passez requireSignInProvider: true lorsqu’un endpoint exige une connexion via ce fournisseur (le sujet est lié et firebase.sign_in_provider correspond). Conservez false (valeur par défaut) pour les vérifications de liaison/dissociation ou les endpoints combinant connexion et liaison qui acceptent aussi des sessions établies via un autre fournisseur. Cette politique relève de l’application.
import { hasFirebaseProviderIdentity, verifyGoogleIdentityToken } from '@rdlabo/workers-hono-kit';
// firebaseVerifier est le FirebaseVerifier configuré par l’application.
const verifiedFirebaseToken = await firebaseVerifier.verifyIdToken(firebaseIdToken);
const subject = await verifyGoogleIdentityToken(googleIdToken, GOOGLE_CLIENT_IDS);
// connexion : exiger une connexion active via Google
if (!hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject, true)) {
return c.json({ error: 'Google identity mismatch' }, 401);
}
// liaison / dissociation : la présence du sujet suffit
// hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject)