feat(hono): add @clerk/hono package #7789
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: c70f7da The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Why:
Migrate the community @hono/clerk-auth package to an official Clerk SDK.
With Hono's rising popularity, we want to offer first-party support with
faster iteration and direct issue triage.
What changed:
- clerkMiddleware() - authenticates requests, attaches auth to Hono context
- getAuth(c) - retrieves auth object from context
- verifyWebhook(c) - webhook verification via @clerk/hono/webhooks
- Type augmentation for c.get('clerk') and c.get('clerkAuth')
API is identical to @hono/clerk-auth for easy migration.
Based on the community package by Vaggelis Yfantis.
nikosdouvlis
force-pushed
the
nikos/hono
branch
from
118484a to
4426c11
Compare
📝 WalkthroughWalkthroughThis pull request adds a new Hono integration package (clerk/hono) including middleware and helpers: a clerkMiddleware for Hono apps, a getAuth utility, and verifyWebhook for webhook verification. It introduces package metadata and build configuration (tsup, tsconfig), TypeScript types and ambient globals, README documentation, tests (Vitest), and CI/dev tooling. New files include source, tests, type re-exports, and packaging configs; scripts were updated to respect changeset ignores. Changesets configuration was updated to ignore the new package. 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. No actionable comments were generated in the recent review. 🎉 Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@packages/hono/README.md`:
- Around line 33-37: Update the "Prerequisites" section to include a
compatibility matrix: under the existing "Prerequisites" heading (currently
listing "Hono 4+" and "Node.js 20+"), add a short table or bullet list that
explicitly maps supported Hono versions to supported Node.js versions (e.g.,
Hono 4.x → Node 20+, Hono 3.x → Node 18 LTS if still supported), indicate which
module formats (ESM/CJS) are supported, and note the minimum tested CI matrix;
ensure the matrix mentions the minimum supported versions and the CI-tested
combinations so consumers can see exact compatibility.
In `@packages/hono/src/clerkMiddleware.ts`:
- Around line 38-43: The destructuring currently uses "options || { env... }"
which treats any provided (even partial) options object as truthy and prevents
fallbacks; change to merge defaults so each field falls back to clerkEnv when
missing: for example, create default values from clerkEnv and then merge with
options (or destructure with per-key defaults) so secretKey, publishableKey,
apiUrl, and apiVersion individually default to clerkEnv.CLERK_SECRET_KEY,
clerkEnv.CLERK_PUBLISHABLE_KEY, clerkEnv.CLERK_API_URL, and
clerkEnv.CLERK_API_VERSION when undefined; update the destructuring of
secretKey, publishableKey, apiUrl, apiVersion (and keep ...rest) in
clerkMiddleware.ts accordingly so partial options no longer block env var
fallbacks.
In `@packages/hono/src/getAuth.ts`:
- Around line 4-26: Add missing JSDoc tags to the public getAuth function:
document each parameter with `@param` (e.g., the Hono context parameter, and the
optional options object such as acceptsToken), add an `@returns` describing the
shape/type of the auth object returned (including userId/session/token typing),
and add an `@throws` describing possible errors (for example when
clerkMiddleware() was not applied or when token validation fails). Update the
existing comment block above getAuth to include these tags and keep existing
`@example` sections intact so the public API docs fully describe inputs, outputs,
and error conditions for getAuth.
In `@packages/hono/src/index.ts`:
- Around line 1-14: This file is a barrel-only index exporting clerkMiddleware,
ClerkMiddlewareOptions, getAuth and ClerkHonoVariables and augmenting Hono's
ContextVariableMap; move the public entrypoint off index.ts by creating a
non-barrel file (e.g., main or entry file) that exports clerkMiddleware,
ClerkMiddlewareOptions, getAuth and the ClerkHonoVariables augmentation (and
preserves the declare module block for ContextVariableMap), update package/build
entry to point at that new module, and delete or convert the current index.ts to
an internal shim (or remove exports) so there is no barrel re-export; ensure all
references/imports in the repo that currently import from the package root are
updated to import from the new file.
| ### Prerequisites | ||
|
|
||
| - Hono 4+ | ||
| - Node.js 20+ | ||
|
|
There was a problem hiding this comment.
Add a compatibility matrix for supported versions.
The README lists prerequisites but does not include the required compatibility matrix.
Suggested update
### Prerequisites
- Hono 4+
- Node.js 20+
+
+### Compatibility Matrix
+| Dependency | Supported versions |
+|---|---|
+| Hono | >= 4 |
+| Node.js | >= 20 |As per coding guidelines, "packages/*/README.md: Maintain compatibility matrices for supported versions".
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Prerequisites | |
| - Hono 4+ | |
| - Node.js 20+ | |
| ### Prerequisites | |
| - Hono 4+ | |
| - Node.js 20+ | |
| ### Compatibility Matrix | |
| | Dependency | Supported versions | | |
| |---|---| | |
| | Hono | >= 4 | | |
| | Node.js | >= 20 | |
🤖 Prompt for AI Agents
In `@packages/hono/README.md` around lines 33 - 37, Update the "Prerequisites"
section to include a compatibility matrix: under the existing "Prerequisites"
heading (currently listing "Hono 4+" and "Node.js 20+"), add a short table or
bullet list that explicitly maps supported Hono versions to supported Node.js
versions (e.g., Hono 4.x → Node 20+, Hono 3.x → Node 18 LTS if still supported),
indicate which module formats (ESM/CJS) are supported, and note the minimum
tested CI matrix; ensure the matrix mentions the minimum supported versions and
the CI-tested combinations so consumers can see exact compatibility.
| const { secretKey, publishableKey, apiUrl, apiVersion, ...rest } = options || { | ||
| secretKey: clerkEnv.CLERK_SECRET_KEY || '', | ||
| publishableKey: clerkEnv.CLERK_PUBLISHABLE_KEY || '', | ||
| apiUrl: clerkEnv.CLERK_API_URL, | ||
| apiVersion: clerkEnv.CLERK_API_VERSION, | ||
| }; |
There was a problem hiding this comment.
Bug: Partial options breaks env var fallback for keys.
When any options object is passed (even partial like { domain: 'example.com' }), the || operator returns the entire options object, causing secretKey and publishableKey to be undefined instead of falling back to environment variables. Users will get "Missing Secret Key" errors despite having CLERK_SECRET_KEY set.
Proposed fix using destructuring defaults
const clerkEnv = env<ClerkEnv>(c);
- const { secretKey, publishableKey, apiUrl, apiVersion, ...rest } = options || {
- secretKey: clerkEnv.CLERK_SECRET_KEY || '',
- publishableKey: clerkEnv.CLERK_PUBLISHABLE_KEY || '',
- apiUrl: clerkEnv.CLERK_API_URL,
- apiVersion: clerkEnv.CLERK_API_VERSION,
- };
+ const {
+ secretKey = clerkEnv.CLERK_SECRET_KEY || '',
+ publishableKey = clerkEnv.CLERK_PUBLISHABLE_KEY || '',
+ apiUrl = clerkEnv.CLERK_API_URL,
+ apiVersion = clerkEnv.CLERK_API_VERSION,
+ ...rest
+ } = options || {};🤖 Prompt for AI Agents
In `@packages/hono/src/clerkMiddleware.ts` around lines 38 - 43, The destructuring
currently uses "options || { env... }" which treats any provided (even partial)
options object as truthy and prevents fallbacks; change to merge defaults so
each field falls back to clerkEnv when missing: for example, create default
values from clerkEnv and then merge with options (or destructure with per-key
defaults) so secretKey, publishableKey, apiUrl, and apiVersion individually
default to clerkEnv.CLERK_SECRET_KEY, clerkEnv.CLERK_PUBLISHABLE_KEY,
clerkEnv.CLERK_API_URL, and clerkEnv.CLERK_API_VERSION when undefined; update
the destructuring of secretKey, publishableKey, apiUrl, apiVersion (and keep
...rest) in clerkMiddleware.ts accordingly so partial options no longer block
env var fallbacks.
| /** | ||
| * Retrieves the Clerk auth object from the Hono context. | ||
| * Must be used after clerkMiddleware() has been applied. | ||
| * | ||
| * @example | ||
| * ```ts | ||
| * app.get('/protected', (c) => { | ||
| * const { userId } = getAuth(c); | ||
| * if (!userId) { | ||
| * return c.json({ error: 'Unauthorized' }, 401); | ||
| * } | ||
| * return c.json({ message: 'Hello!' }); | ||
| * }); | ||
| * ``` | ||
| * | ||
| * @example Using acceptsToken for API keys | ||
| * ```ts | ||
| * app.get('/api', (c) => { | ||
| * const auth = getAuth(c, { acceptsToken: 'api_key' }); | ||
| * // auth will be typed for API key tokens | ||
| * }); | ||
| * ``` | ||
| */ |
There was a problem hiding this comment.
Public API JSDoc missing required tags.
The JSDoc for getAuth omits mandatory @param, @returns, and @throws tags for public APIs.
Suggested update
/**
* Retrieves the Clerk auth object from the Hono context.
* Must be used after clerkMiddleware() has been applied.
+ *
+ * `@param` c - Hono context.
+ * `@param` options - Optional auth options (e.g., acceptsToken).
+ * `@returns` The auth object for the current request.
+ * `@throws` Error if clerkMiddleware() was not applied.
*
* `@example`
* ```tsAs per coding guidelines, "Document functions with JSDoc comments including @param, @returns, @throws, and @example tags".
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Retrieves the Clerk auth object from the Hono context. | |
| * Must be used after clerkMiddleware() has been applied. | |
| * | |
| * @example | |
| * ```ts | |
| * app.get('/protected', (c) => { | |
| * const { userId } = getAuth(c); | |
| * if (!userId) { | |
| * return c.json({ error: 'Unauthorized' }, 401); | |
| * } | |
| * return c.json({ message: 'Hello!' }); | |
| * }); | |
| * ``` | |
| * | |
| * @example Using acceptsToken for API keys | |
| * ```ts | |
| * app.get('/api', (c) => { | |
| * const auth = getAuth(c, { acceptsToken: 'api_key' }); | |
| * // auth will be typed for API key tokens | |
| * }); | |
| * ``` | |
| */ | |
| /** | |
| * Retrieves the Clerk auth object from the Hono context. | |
| * Must be used after clerkMiddleware() has been applied. | |
| * | |
| * `@param` c - Hono context. | |
| * `@param` options - Optional auth options (e.g., acceptsToken). | |
| * `@returns` The auth object for the current request. | |
| * `@throws` Error if clerkMiddleware() was not applied. | |
| * | |
| * `@example` | |
| * |
🤖 Prompt for AI Agents
In `@packages/hono/src/getAuth.ts` around lines 4 - 26, Add missing JSDoc tags to
the public getAuth function: document each parameter with `@param` (e.g., the Hono
context parameter, and the optional options object such as acceptsToken), add an
`@returns` describing the shape/type of the auth object returned (including
userId/session/token typing), and add an `@throws` describing possible errors (for
example when clerkMiddleware() was not applied or when token validation fails).
Update the existing comment block above getAuth to include these tags and keep
existing `@example` sections intact so the public API docs fully describe inputs,
outputs, and error conditions for getAuth.
| export { clerkMiddleware } from './clerkMiddleware'; | ||
| export type { ClerkMiddlewareOptions } from './clerkMiddleware'; | ||
|
|
||
| export { getAuth } from './getAuth'; | ||
|
|
||
| import type { ClerkHonoVariables } from './types'; | ||
| export type { ClerkHonoVariables }; | ||
|
|
||
| // Augment Hono's ContextVariableMap so users get type inference | ||
| // for c.get('clerk') and c.get('clerkAuth') | ||
| declare module 'hono' { | ||
| // eslint-disable-next-line @typescript-eslint/no-empty-object-type | ||
| interface ContextVariableMap extends ClerkHonoVariables {} | ||
| } |
There was a problem hiding this comment.
Avoid barrel-style re-exports in index.ts.
This file is a pure re-export barrel, which the guidelines prohibit. Please move the public entrypoint to a non-index.ts file (and update the build/package entry) or otherwise eliminate the barrel-only index.
As per coding guidelines, "**/index.ts: Avoid barrel files (index.ts re-exports) as they can cause circular dependencies".
🤖 Prompt for AI Agents
In `@packages/hono/src/index.ts` around lines 1 - 14, This file is a barrel-only
index exporting clerkMiddleware, ClerkMiddlewareOptions, getAuth and
ClerkHonoVariables and augmenting Hono's ContextVariableMap; move the public
entrypoint off index.ts by creating a non-barrel file (e.g., main or entry file)
that exports clerkMiddleware, ClerkMiddlewareOptions, getAuth and the
ClerkHonoVariables augmentation (and preserves the declare module block for
ContextVariableMap), update package/build entry to point at that new module, and
delete or convert the current index.ts to an internal shim (or remove exports)
so there is no barrel re-export; ensure all references/imports in the repo that
currently import from the package root are updated to import from the new file.
The snapshot and canary scripts generate a changeset listing all packages, but @clerk/hono is in the changeset ignore list. This creates a mixed changeset (ignored + non-ignored packages) which changesets doesn't allow, breaking CI.
2 participants
Why
The community
@hono/clerk-authpackage has been the go-to for Clerk + Hono users, but as Hono's popularity grows we want to offer first-party support with faster iteration and direct issue triage.This PR adds
@clerk/hono, an official Clerk SDK for Hono that provides:clerkMiddleware()- authenticates requests and attaches auth to Hono contextgetAuth(c)- retrieves the auth object from contextverifyWebhook(c)- webhook verification via@clerk/hono/webhooksc.get('clerk')andc.get('clerkAuth')The API is identical to
@hono/clerk-authfor easy migration. Based on the community package by Vaggelis Yfantis.The package is excluded from releases for now, as we want to collaborate with the Hono team on the migration path from
@hono/clerk-authbefore publishing.Test plan
clerkMiddlewareandgetAuthSummary by CodeRabbit