Uh oh!
There was an error while loading. Please reload this page.
fix(fastify): Use runtime keys for Clerk client - #8640
Conversation
Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
🦋 Changeset detectedLatest commit: dc9a5c1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
The latest updates on your projects. Learn more about Vercel for GitHub.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR exposes the runtime-created Clerk client on Fastify requests. It augments FastifyRequest with Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/fastify/src/types.ts`:
- Around line 4-7: The FastifyRequest augmentation declares clerk as ClerkClient
but the runtime plugin calls instance.decorateRequest('clerk', null); causing a
type mismatch—change the augmented type to allow null (e.g.,
FastifyRequest.clerk: ClerkClient | null) so it matches the decorateRequest
initialization; update the declaration in types.ts referencing
FastifyRequest.clerk and ensure any code using clerk handles the nullable type
or narrows it before use.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 27764212-21cd-44c6-a734-3cc813337102
📒 Files selected for processing (6)
.changeset/silent-fastify-handshakes.mdpackages/fastify/src/__tests__/clerkPlugin.test.tspackages/fastify/src/__tests__/withClerkMiddleware.test.tspackages/fastify/src/clerkPlugin.tspackages/fastify/src/types.tspackages/fastify/src/withClerkMiddleware.ts
| declare module 'fastify' { | ||
| interface FastifyRequest { | ||
| clerk: ClerkClient; | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash# Verify the type/decorator contract mismatch locations
rg -n "interface FastifyRequest|clerk:\\s*ClerkClient|decorateRequest\\('clerk'" packages/fastify/src/types.ts packages/fastify/src/clerkPlugin.tsRepository: clerk/javascript
Length of output: 259
Fix FastifyRequest.clerk type to match decorateRequest initialization
packages/fastify/src/types.ts declares FastifyRequest.clerk: ClerkClient, but packages/fastify/src/clerkPlugin.ts initializes it via instance.decorateRequest('clerk', null);, creating a compile-time type contract mismatch. Align the runtime value with the augmented type (e.g., make it nullable).
Suggested minimal fix
declare module 'fastify' {
interface FastifyRequest {
- clerk: ClerkClient;+ clerk: ClerkClient | null;
}
}📝 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.
| declare module 'fastify'{ | |
| interfaceFastifyRequest{ | |
| clerk: ClerkClient; | |
| } | |
| declare module 'fastify'{ | |
| interfaceFastifyRequest{ | |
| clerk: ClerkClient|null; | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/fastify/src/types.ts` around lines 4 - 7, The FastifyRequest
augmentation declares clerk as ClerkClient but the runtime plugin calls
instance.decorateRequest('clerk', null); causing a type mismatch—change the
augmented type to allow null (e.g., FastifyRequest.clerk: ClerkClient | null) so
it matches the decorateRequest initialization; update the declaration in
types.ts referencing FastifyRequest.clerk and ensure any code using clerk
handles the nullable type or narrows it before use.
There was a problem hiding this comment.
From Fastify Decorator docs:
Keep the initial shape of a decorated field close to its future dynamic value. Initialize a decorator as '' for strings and null for objects or functions.
So this is just a placehodler required by Fastify API and the value is always set to the actual ClerkClient before any route handler runs
There was a problem hiding this comment.
@wobsoriano, that makes sense — the null initialization is purely a Fastify/V8 optimization hint and not a value that consumers ever see. The non-nullable clerk: ClerkClient type is correct. Sorry for the noise!
✏️ Learnings added
Learnt from: wobsoriano
Repo: clerk/javascript PR: 8640
File: packages/fastify/src/types.ts:4-7
Timestamp: 2026-05-29T20:36:33.106Z
Learning: In the Fastify integration (`packages/fastify/src/clerkPlugin.ts` and `packages/fastify/src/types.ts`), `instance.decorateRequest('clerk', null)` uses `null` as a required Fastify API placeholder (V8 shape hint) — not a runtime null. The `clerk` property is always assigned to a real `ClerkClient` before any route handler executes, so `FastifyRequest.clerk: ClerkClient` (non-nullable) is the correct type augmentation. Do not flag this as a type mismatch.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: wobsoriano
Repo: clerk/javascript PR: 7883
File: packages/backend/src/api/__tests__/M2MTokenApi.test.ts:414-419
Timestamp: 2026-02-24T18:03:27.067Z
Learning: In TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs, but allow internal test helper functions without explicit return types. This helps maintain API clarity and type safety for consumers while not burdening test helpers that are not part of the public surface.
@clerk/astro@clerk/backend@clerk/chrome-extension@clerk/clerk-js@clerk/expo@clerk/expo-passkeys@clerk/express@clerk/fastify@clerk/hono@clerk/localizations@clerk/nextjs@clerk/nuxt@clerk/react@clerk/react-router@clerk/shared@clerk/tanstack-react-start@clerk/testing@clerk/ui@clerk/upgrade@clerk/vuecommit: |
Description
Cherry picked from #8560, focused on creating a
clerkClientfrom resolved runtime middleware options before callingauthenticateRequest.This also adds a
clerkproperty to the request object similar to how the Hono SDK passes the inner Clerk client from middleware, so devs can access the same runtime-configured client in route handlers viarequest.clerk. This is useful when keys are provided directly toclerkPlugin()at runtime, since downstream Backend API calls will use the same resolved options as authentication.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change