Skip to content

Commit 14ca5e4

Browse files
nikosdouvlisnikosdouvlis
authored
feat(hono): add @clerk/hono package
The community @hono/clerk-auth package 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 adds @clerk/hono with an API identical to @hono/clerk-auth for easy migration. Based on the community package by Vaggelis Yfantis. Changes: - 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') - Package excluded from releases until migration path with Hono team is decided - Snapshot/canary scripts updated to respect changeset ignore list
1 parent ed8dc4d commit 14ca5e4

23 files changed

Lines changed: 861 additions & 6 deletions

‎.changeset/clerk-hono-initial.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
'@clerk/hono': minor
3+
---
4+
5+
Initial release of `@clerk/hono` - the official Clerk SDK for Hono.
6+
7+
This package provides:
8+
- `clerkMiddleware()` - Middleware to authenticate requests and attach auth data to Hono context
9+
- `getAuth(c)` - Helper to retrieve auth data from Hono context
10+
- `verifyWebhook(c)` - Webhook verification via `@clerk/hono/webhooks`
11+
12+
**Usage:**
13+
14+
```typescript
15+
import { Hono } from 'hono';
16+
import { clerkMiddleware, getAuth } from '@clerk/hono';
17+
18+
const app = new Hono();
19+
20+
app.use('*', clerkMiddleware());
21+
22+
app.get('/protected', (c) => {
23+
const { userId } = getAuth(c);
24+
if (!userId) {
25+
return c.json({ error: 'Unauthorized' }, 401);
26+
}
27+
return c.json({ userId });
28+
});
29+
```
30+
31+
Based on the community `@hono/clerk-auth` package. Thank you to Vaggelis Yfantis for the original implementation!

‎.changeset/config.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
}
88
],
99
"commit": false,
10+
"ignore": ["@clerk/hono"],
1011
"fixed": [],
1112
"linked": [],
1213
"access": "public",

‎packages/hono/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
<p align="center">
2+
<a href="https://clerk.com?utm_source=github&utm_medium=clerk_hono" target="_blank" rel="noopener noreferrer">
3+
<picture>
4+
<source media="(prefers-color-scheme: dark)" srcset="https://images.clerk.com/static/logo-dark-mode-400x400.png">
5+
<img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64">
6+
</picture>
7+
</a>
8+
<br />
9+
</p>
10+
11+
# @clerk/hono
12+
13+
<div align="center">
14+
15+
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord)
16+
[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_hono)
17+
[![Follow on Twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)
18+
19+
[Changelog](https://github.com/clerk/javascript/blob/main/packages/hono/CHANGELOG.md)
20+
·
21+
[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml)
22+
·
23+
[Request a Feature](https://feedback.clerk.com/roadmap)
24+
·
25+
[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_hono)
26+
27+
</div>
28+
29+
## Getting Started
30+
31+
[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_hono) is the easiest way to add authentication and user management to your Hono application. Add sign up, sign in, and profile management to your application in minutes.
32+
33+
### Prerequisites
34+
35+
- Hono 4+
36+
- Node.js 20+
37+
38+
### Installation
39+
40+
```sh
41+
npm install @clerk/hono
42+
```
43+
44+
### Configuration
45+
46+
Set your Clerk API keys as environment variables:
47+
48+
```sh
49+
CLERK_SECRET_KEY=sk_****
50+
CLERK_PUBLISHABLE_KEY=pk_****
51+
```
52+
53+
### Usage
54+
55+
```typescript
56+
import { Hono } from 'hono';
57+
import { clerkMiddleware, getAuth } from '@clerk/hono';
58+
59+
const app = new Hono();
60+
61+
// Apply Clerk middleware to all routes
62+
app.use('*', clerkMiddleware());
63+
64+
// Public route
65+
app.get('/', c => {
66+
return c.json({ message: 'Hello!' });
67+
});
68+
69+
// Protected route
70+
app.get('/protected', c => {
71+
const { userId } = getAuth(c);
72+
73+
if (!userId) {
74+
return c.json({ error: 'Unauthorized' }, 401);
75+
}
76+
77+
return c.json({ message: 'Hello authenticated user!', userId });
78+
});
79+
80+
export default app;
81+
```
82+
83+
### Accessing the Clerk Client
84+
85+
You can access the Clerk Backend API client directly from the context:
86+
87+
```typescript
88+
app.get('/user/:id', async c => {
89+
const clerkClient = c.get('clerk');
90+
const user = await clerkClient.users.getUser(c.req.param('id'));
91+
return c.json({ user });
92+
});
93+
```
94+
95+
### Using `acceptsToken` for Machine Auth
96+
97+
```typescript
98+
app.get('/api', c => {
99+
const auth = getAuth(c, { acceptsToken: 'api_key' });
100+
101+
if (!auth.userId) {
102+
return c.json({ error: 'Unauthorized' }, 401);
103+
}
104+
105+
return c.json({ message: 'API access granted' });
106+
});
107+
```
108+
109+
### Webhook Verification
110+
111+
```typescript
112+
import { Hono } from 'hono';
113+
import { verifyWebhook } from '@clerk/hono/webhooks';
114+
115+
const app = new Hono();
116+
117+
app.post('/webhooks/clerk', async c => {
118+
const evt = await verifyWebhook(c);
119+
120+
switch (evt.type) {
121+
case 'user.created':
122+
console.log('User created:', evt.data.id);
123+
break;
124+
// Handle other event types...
125+
}
126+
127+
return c.json({ received: true });
128+
});
129+
```
130+
131+
## Support
132+
133+
You can get in touch with us in any of the following ways:
134+
135+
- Join our official community [Discord server](https://clerk.com/discord)
136+
- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_hono)
137+
138+
## Contributing
139+
140+
We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md).
141+
142+
## Security
143+
144+
`@clerk/hono` follows good practices of security, but 100% security cannot be assured.
145+
146+
`@clerk/hono` is provided **"as is"** without any **warranty**. Use at your own risk.
147+
148+
_For more information and to report security issues, please refer to our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._
149+
150+
## License
151+
152+
This project is licensed under the **MIT license**.
153+
154+
See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/hono/LICENSE) for more information.

‎packages/hono/package.json‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
{
2+
"name": "@clerk/hono",
3+
"version": "0.0.1",
4+
"description": "Clerk SDK for Hono",
5+
"keywords": [
6+
"auth",
7+
"authentication",
8+
"passwordless",
9+
"session",
10+
"jwt",
11+
"hono",
12+
"clerk"
13+
],
14+
"homepage": "https://clerk.com/",
15+
"bugs": {
16+
"url": "https://github.com/clerk/javascript/issues"
17+
},
18+
"repository": {
19+
"type": "git",
20+
"url": "git+https://github.com/clerk/javascript.git",
21+
"directory": "packages/hono"
22+
},
23+
"license": "MIT",
24+
"author": "Clerk",
25+
"sideEffects": false,
26+
"exports": {
27+
".": {
28+
"import": {
29+
"types": "./dist/index.d.mts",
30+
"default": "./dist/index.mjs"
31+
},
32+
"require": {
33+
"types": "./dist/index.d.ts",
34+
"default": "./dist/index.js"
35+
}
36+
},
37+
"./webhooks": {
38+
"import": {
39+
"types": "./dist/webhooks.d.mts",
40+
"default": "./dist/webhooks.mjs"
41+
},
42+
"require": {
43+
"types": "./dist/webhooks.d.ts",
44+
"default": "./dist/webhooks.js"
45+
}
46+
},
47+
"./types": {
48+
"import": {
49+
"types": "./dist/types.d.mts"
50+
},
51+
"require": {
52+
"types": "./dist/types.d.ts"
53+
}
54+
}
55+
},
56+
"main": "./dist/index.js",
57+
"module": "./dist/index.mjs",
58+
"types": "./dist/index.d.ts",
59+
"files": [
60+
"dist"
61+
],
62+
"scripts": {
63+
"build": "tsup --env.NODE_ENV production",
64+
"clean": "rimraf ./dist",
65+
"dev": "tsup --watch",
66+
"format": "node ../../scripts/format-package.mjs",
67+
"format:check": "node ../../scripts/format-package.mjs --check",
68+
"lint": "eslint src",
69+
"lint:attw": "attw --pack . --profile node16",
70+
"lint:publint": "publint",
71+
"publish:local": "pnpm yalc push --replace --sig",
72+
"test": "vitest run",
73+
"test:watch": "vitest watch"
74+
},
75+
"dependencies": {
76+
"@clerk/backend": "workspace:^",
77+
"@clerk/shared": "workspace:^"
78+
},
79+
"devDependencies": {
80+
"hono": "^4.7.4"
81+
},
82+
"peerDependencies": {
83+
"hono": ">=4"
84+
},
85+
"engines": {
86+
"node": ">=20"
87+
},
88+
"publishConfig": {
89+
"access": "public"
90+
}
91+
}

‎packages/hono/src/__tests__/__snapshots__/exports.test.ts.snap‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
2+
3+
exports[`@clerk/hono public exports > should not include a breaking change 1`] = `
4+
[
5+
"clerkMiddleware",
6+
"getAuth",
7+
]
8+
`;

0 commit comments

Comments
 (0)