feat(fastify): Add Frontend API proxy support by nikosdouvlis · Pull Request #7995 · clerk/javascript

nikosdouvlis · 2026-03-05T11:43:21Z

This adds a frontendApiProxy option to clerkPlugin:

server.register(clerkPlugin, {
  frontendApiProxy: { enabled: true }
});

What's included:

FrontendApiProxyOptions type and frontendApiProxy option on ClerkFastifyOptions
Proxy interception in withClerkMiddleware before auth - matching requests are converted to Fetch Request, forwarded to FAPI via clerkFrontendApiProxy, and streamed back through Fastify's reply using Node.js Readable streams
requestToProxyRequest utility for creating Fetch Requests with real URLs and body streaming from Fastify requests
Auto-derives proxyUrl for auth handshake from x-forwarded-proto/x-forwarded-host headers
7 unit tests using Fastify's inject() covering interception, custom paths, disabled/unconfigured states, and proxyUrl derivation

Summary by CodeRabbit

Release Notes

New Features
- Added Frontend API proxy support to Fastify integration, enabling secure request forwarding through a configurable proxy path (default /__clerk). Automatically derives proxy URL from incoming request headers. Helps environments where direct API access is blocked by ad blockers or firewalls.
Tests
- Added comprehensive test coverage for new Frontend API proxy functionality.

Why: Ad blockers and corporate firewalls can block direct connections to Clerk's Frontend API. Express and Next.js already have proxy support, but Fastify didn't, leaving Fastify users without a workaround. What changed: - Added `FrontendApiProxyOptions` type and `frontendApiProxy` option to `ClerkFastifyOptions` - Proxy interception in `withClerkMiddleware` runs before auth: matching requests are converted to Fetch Request, forwarded to FAPI via `clerkFrontendApiProxy`, and streamed back through Fastify's reply - Added `requestToProxyRequest` utility for creating Fetch Requests with real URLs and body streaming from Fastify requests - Auto-derives `proxyUrl` for auth handshake from `x-forwarded-proto`/`x-forwarded-host` headers when proxy is enabled - Added 7 unit tests covering interception, custom paths, disabled/unconfigured states, and proxyUrl derivation

vercel · 2026-03-05T11:43:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 5, 2026 11:43am

changeset-bot · 2026-03-05T11:43:30Z

🦋 Changeset detected

Latest commit: c056d3a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/fastify	Minor

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

pkg-pr-new · 2026-03-05T11:46:17Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7995

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7995

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7995

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7995

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7995

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7995

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7995

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7995

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7995

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7995

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@7995

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7995

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7995

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7995

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7995

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7995

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7995

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7995

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7995

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7995

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7995

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7995

commit: c056d3a

coderabbitai · 2026-03-05T11:47:58Z

📝 Walkthrough

Walkthrough

This pull request introduces Frontend API proxy support to the @clerk/fastify package. It adds a new frontendApiProxy option to the Fastify plugin configuration that enables intercepting and forwarding requests under a configurable path (default: /__clerk) to Clerk's Frontend API. The implementation includes new type definitions, utility functions for request conversion, middleware logic for routing and proxying requests, and comprehensive test coverage. The feature automatically derives the proxy URL from request headers when needed.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(fastify): Add Frontend API proxy support' directly and accurately summarizes the main change—adding Frontend API proxy support to the Fastify integration.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

dominic-clerk · 2026-03-06T06:45:25Z

!snapshot

clerk-cookie · 2026-03-06T06:47:57Z

Hey @dominic-clerk - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.3.2-snapshot.v20260306064615
@clerk/astro	3.0.2-snapshot.v20260306064615
@clerk/backend	3.0.2-snapshot.v20260306064615
@clerk/chrome-extension	3.0.2-snapshot.v20260306064615
@clerk/clerk-js	6.0.1-snapshot.v20260306064615
@clerk/dev-cli	0.1.1-snapshot.v20260306064615
@clerk/expo	3.0.2-snapshot.v20260306064615
@clerk/expo-passkeys	1.0.2-snapshot.v20260306064615
@clerk/express	2.0.2-snapshot.v20260306064615
@clerk/fastify	3.1.0-snapshot.v20260306064615
@clerk/hono	0.0.4-snapshot.v20260306064615
@clerk/localizations	4.0.1-snapshot.v20260306064615
@clerk/msw	0.0.2-snapshot.v20260306064615
@clerk/nextjs	7.0.2-snapshot.v20260306064615
@clerk/nuxt	2.0.2-snapshot.v20260306064615
@clerk/react	6.0.2-snapshot.v20260306064615
@clerk/react-router	3.0.2-snapshot.v20260306064615
@clerk/shared	4.0.1-snapshot.v20260306064615
@clerk/tanstack-react-start	1.0.2-snapshot.v20260306064615
@clerk/testing	2.0.2-snapshot.v20260306064615
@clerk/ui	1.0.2-snapshot.v20260306064615
@clerk/upgrade	2.0.2-snapshot.v20260306064615
@clerk/vue	2.0.2-snapshot.v20260306064615

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.3.2-snapshot.v20260306064615 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.2-snapshot.v20260306064615 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.2-snapshot.v20260306064615 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.2-snapshot.v20260306064615 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.1-snapshot.v20260306064615 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260306064615 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.2-snapshot.v20260306064615 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.2-snapshot.v20260306064615 --save-exact

@clerk/express

npm i @clerk/express@2.0.2-snapshot.v20260306064615 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.0-snapshot.v20260306064615 --save-exact

@clerk/hono

npm i @clerk/hono@0.0.4-snapshot.v20260306064615 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.1-snapshot.v20260306064615 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.2-snapshot.v20260306064615 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.2-snapshot.v20260306064615 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.2-snapshot.v20260306064615 --save-exact

@clerk/react

npm i @clerk/react@6.0.2-snapshot.v20260306064615 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.2-snapshot.v20260306064615 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.1-snapshot.v20260306064615 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.2-snapshot.v20260306064615 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.2-snapshot.v20260306064615 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.2-snapshot.v20260306064615 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.2-snapshot.v20260306064615 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.2-snapshot.v20260306064615 --save-exact

github-actions bot added the fastify label Mar 5, 2026

vercel bot deployed to Preview March 5, 2026 11:43 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(fastify): Add Frontend API proxy support#7995

feat(fastify): Add Frontend API proxy support#7995
nikosdouvlis wants to merge 1 commit intomainfrom
nikos/fastify-proxy-support

nikosdouvlis commented Mar 5, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Mar 5, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 5, 2026

Uh oh!

pkg-pr-new bot commented Mar 5, 2026

Uh oh!

coderabbitai bot commented Mar 5, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk commented Mar 6, 2026

Uh oh!

clerk-cookie commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nikosdouvlis commented Mar 5, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Release Notes

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 5, 2026

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Mar 5, 2026

Uh oh!

coderabbitai bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk commented Mar 6, 2026

Uh oh!

clerk-cookie commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nikosdouvlis commented Mar 5, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading

coderabbitai bot commented Mar 5, 2026 •

edited

Loading