Skip to content

feat(*): auto-proxy for eligible hosts#8035

Open
brkalow wants to merge 3 commits intomainfrom
brkalow/auto-proxy-vercel-subdomains
Open

feat(*): auto-proxy for eligible hosts#8035
brkalow wants to merge 3 commits intomainfrom
brkalow/auto-proxy-vercel-subdomains

Conversation

@brkalow
Copy link
Member

@brkalow brkalow commented Mar 11, 2026

Description

This PR implements automatic FAPI proxying for Vercel preview deployments. When an app is deployed to a .vercel.app subdomain without explicit proxy or domain configuration, the SDK automatically routes FAPI requests through the app's own domain via the /__clerk proxy path.

The auto-detection is centralized across all SDKs:

  • Shared utilities (@clerk/shared/proxy): New isVercelPreviewDeploy() helper detects .vercel.app hostnames
  • Client-side (@clerk/clerk-js): Auto-detect in proxyUrl getter when window.location.hostname is .vercel.app
  • Server-side (@clerk/backend): Auto-detect in authenticateContext constructor when request hostname is .vercel.app
  • Next.js middleware (@clerk/nextjs): Auto-enable proxy interception for /__clerk/* requests on .vercel.app hostnames

Guard conditions prevent auto-detection when explicit configuration is provided: proxyUrl, domain, or environment variables NEXT_PUBLIC_CLERK_PROXY_URL / NEXT_PUBLIC_CLERK_DOMAIN.

Test Results

  • @clerk/shared: 981/981 tests passed
  • @clerk/backend: 1114/1114 tests passed
  • @clerk/clerk-js: 624/624 tests passed
  • @clerk/nextjs: 362 tests passed (49 pre-existing failures unrelated to this change)

Build verification: All packages build cleanly with no type errors.

Checklist

  • pnpm test runs as expected
  • pnpm build runs as expected
  • Tests added for new functionality

Type of change

  • 🌟 New feature

Summary by CodeRabbit

  • New Features

    • Automatic proxy detection for Vercel preview-style hosts: when no explicit proxy or domain is set, the system can auto-configure frontend API routing for eligible hosts; explicit proxy or domain settings still take precedence.
  • Tests

    • Added tests covering auto-detection behavior, precedence rules, and various host scenarios.

@vercel
Copy link

vercel bot commented Mar 11, 2026

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

Project Deployment Actions Updated (UTC)
clerk-js-sandbox Ready Ready Preview, Comment Mar 13, 2026 1:42am

Request Review

@changeset-bot
Copy link

changeset-bot bot commented Mar 11, 2026

🦋 Changeset detected

Latest commit: 2d729d2

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

This PR includes changesets to release 21 packages
Name Type
@clerk/backend Patch
@clerk/clerk-js Patch
@clerk/nextjs Patch
@clerk/shared Patch
@clerk/agent-toolkit Patch
@clerk/astro Patch
@clerk/express Patch
@clerk/fastify Patch
@clerk/hono Patch
@clerk/nuxt Patch
@clerk/react-router Patch
@clerk/tanstack-react-start Patch
@clerk/testing Patch
@clerk/chrome-extension Patch
@clerk/expo Patch
@clerk/expo-passkeys Patch
@clerk/localizations Patch
@clerk/msw Patch
@clerk/react Patch
@clerk/ui Patch
@clerk/vue Patch

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

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 11, 2026

📝 Walkthrough

Walkthrough

Adds exported predicate shouldAutoProxy(hostname: string) to the shared package (matches .vercel.app). Integrates it into backend AuthenticateContext, Clerk core, and Next.js middleware to auto-set proxy URL to the current origin + /__clerk when neither proxyUrl nor domain is provided and the hostname is eligible. Tests added across packages to verify auto-detection and precedence of explicit settings.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% 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
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'feat(*): auto-proxy for eligible hosts' directly and clearly describes the main feature added across the changeset: automatic proxy detection for eligible hosting environments (Vercel .vercel.app subdomains).

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

📝 Coding Plan
  • Generate coding plan for human review comments

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

…omains

Add automatic FAPI proxying detection for Vercel preview deployments across all SDKs. When an app is deployed to a .vercel.app subdomain without explicit proxy/domain configuration, the SDK automatically routes FAPI requests through the app's own domain via /__clerk proxy path.

- Add isVercelPreviewDeploy() helper in @clerk/shared/proxy
- Auto-detect in clerk-js proxyUrl getter for client-side SDK initialization
- Auto-detect in @clerk/backend authenticateContext for server-side auth
- Enable proxy interception in Next.js middleware for /__clerk/* requests on .vercel.app
- Add comprehensive tests for all three layers (shared, backend, clerk-js, nextjs)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
@pkg-pr-new
Copy link

pkg-pr-new bot commented Mar 13, 2026

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 2d729d2

@brkalow brkalow changed the title Auto-proxy for .vercel.app subdomains feat(*): auto-proxy for eligible hosts Mar 13, 2026
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.changeset/tiny-badgers-smile.md:
- Line 8: Update the changeset description sentence that currently reads "Add
auto-proxy detection for eligible hosts and generalize the internal helper
naming for future providers." to be specific about which hosts are considered
eligible (e.g., Vercel preview deployments) and to clarify the helper change;
for example, change the description to: "Add auto-proxy detection for Vercel
preview deployments (.vercel.app subdomains) and generalize the internal helper
for future hosting providers." Locate and edit the line containing that
description in the changeset (the sentence beginning "Add auto-proxy detection
for eligible hosts...") and replace it with the clearer, user-facing wording.
- Around line 1-6: The changeset incorrectly marks package bumps as 'patch' but
a new public API (shouldAutoProxy) was added; update the entries so any package
that exports the new function (at least '@clerk/shared', and any packages that
re-export it like '@clerk/backend', '@clerk/clerk-js', '@clerk/nextjs' if
applicable) use 'minor' instead of 'patch' in the
.changeset/tiny-badgers-smile.md file; ensure the header lines for those package
entries read 'minor' to reflect the new public API bump while keeping other
metadata unchanged.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0cecde51-9659-43c2-8677-37774a033a71

📥 Commits

Reviewing files that changed from the base of the PR and between dbc580e and 2d729d2.

📒 Files selected for processing (1)
  • .changeset/tiny-badgers-smile.md

Comment on lines +1 to +6
---
'@clerk/backend': patch
'@clerk/clerk-js': patch
'@clerk/nextjs': patch
'@clerk/shared': patch
---
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check if shouldAutoProxy is a public export

# Search for shouldAutoProxy exports in the shared package
rg -n "export.*shouldAutoProxy" packages/shared/

Repository: clerk/javascript

Length of output: 152


Update version bumps from patch to minor to reflect the new public API export.

The changeset marks all packages for patch bumps, but the PR introduces a new public API function shouldAutoProxy exported from @clerk/shared. Per semantic versioning standards, new public APIs require minor version bumps, not patch (which is reserved for bug fixes). Update the changeset accordingly.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.changeset/tiny-badgers-smile.md around lines 1 - 6, The changeset
incorrectly marks package bumps as 'patch' but a new public API
(shouldAutoProxy) was added; update the entries so any package that exports the
new function (at least '@clerk/shared', and any packages that re-export it like
'@clerk/backend', '@clerk/clerk-js', '@clerk/nextjs' if applicable) use 'minor'
instead of 'patch' in the .changeset/tiny-badgers-smile.md file; ensure the
header lines for those package entries read 'minor' to reflect the new public
API bump while keeping other metadata unchanged.

'@clerk/shared': patch
---

Add auto-proxy detection for eligible hosts and generalize the internal helper naming for future providers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Consider making the description more specific for end users.

The description mentions "eligible hosts" without specifying what makes a host eligible. Since changeset descriptions appear in changelogs, consider being more explicit to help users understand when auto-proxy detection activates.

For example: "Add auto-proxy detection for Vercel preview deployments (.vercel.app subdomains) and generalize the internal helper for future hosting providers."

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 8-8: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.changeset/tiny-badgers-smile.md at line 8, Update the changeset description
sentence that currently reads "Add auto-proxy detection for eligible hosts and
generalize the internal helper naming for future providers." to be specific
about which hosts are considered eligible (e.g., Vercel preview deployments) and
to clarify the helper change; for example, change the description to: "Add
auto-proxy detection for Vercel preview deployments (.vercel.app subdomains) and
generalize the internal helper for future hosting providers." Locate and edit
the line containing that description in the changeset (the sentence beginning
"Add auto-proxy detection for eligible hosts...") and replace it with the
clearer, user-facing wording.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant