fix(shared): exclude server runtimes from the worker navigator fallback

[jacekradko]

Follow-up to #8827. While reviewing it we checked how the new worker-scope navigator fallback behaves on server runtimes with worker-like globals. Running the probe in real workerd (via miniflare, old and current compatibility dates) showed Cloudflare Workers expose the WorkerGlobalScope constructor but self instanceof WorkerGlobalScope evaluates to false, so the merged gate excludes them today only through that quirk of workerd's prototype chain. If workerd ever aligns with the spec (where ServiceWorkerGlobalScope inherits from WorkerGlobalScope), CF would pass the gate, and since it implements no navigator.onLine, isBrowserOnline would default to true.

Server worker runtimes self-identify in navigator.userAgent (Cloudflare-Workers, Node.js/24, Deno/2.5.0, Bun/1.3.9), so the fallback now rejects those before returning a worker navigator. Browser web/service workers (the MV3 case #8827 fixed) are unaffected; tests cover both today's workerd shape and a simulated spec-compliant one.

Summary by CodeRabbit

Bug Fixes

• Fixed server-side worker environments (Cloudflare Workers, Node.js, Deno, Bun) from being incorrectly identified as valid browsers in runtime validation checks.

Tests

• Added test coverage for browser detection in worker-like environments to verify server runtimes are properly excluded.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 12, 2026 4:01am
swingset	Ready	Preview, Comment	Jun 12, 2026 4:01am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 7c4cd878-b8c5-4426-99bf-2c4fc38c19aa

📥 Commits

Reviewing files that changed from the base of the PR and between c2ba971 and fd2dfcc.

📒 Files selected for processing (3)

• .changeset/shared-worker-navigator-server-runtimes.md
• packages/shared/src/__tests__/browser.spec.ts
• packages/shared/src/browser.ts

---

📝 Walkthrough

Walkthrough

The PR tightens browser detection in @clerk/shared by preventing server-side worker environments from incorrectly passing as valid browsers. A new serverRuntimeUserAgentRegex pattern identifies server runtimes via navigator.userAgent, and getNavigator() now rejects those identifiers. Tests validate the exclusion for Cloudflare Workers, Node.js, Deno, and Bun runtimes.

Changes

Server-runtime exclusion from browser detection

Layer / File(s)	Summary
Server runtime detection pattern and implementation packages/shared/src/browser.ts	Introduces serverRuntimeUserAgentRegex constant documenting worker-like server runtimes (Cloudflare-Workers, Node.js, Deno, Bun) and extends getNavigator() to return null when self.navigator.userAgent matches a server runtime identifier, preventing those environments from being treated as valid browsers.
Test validation for browser and online detection packages/shared/src/__tests__/browser.spec.ts	Extends isValidBrowser() test coverage with parameterized cases for server-runtime user agents, an explicit Cloudflare-Workers test, and a workerd edge case; adds isValidBrowserOnline() test asserting false for server-runtime workers where navigator.onLine is undefined.
Release documentation .changeset/shared-worker-navigator-server-runtimes.md	Documents patch-level change to @clerk/shared describing the navigator fallback exclusion of self-identified server runtimes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• clerk/javascript#8827: Both PRs modify browser/runtime detection around the global self.navigator fallback in worker-like environments, with this PR further tightening it by excluding server-identifying user agents.

Suggested labels

clerk-js

Suggested reviewers

• tmilewski

Poem

🐰 A curious rabbit hops through runtimes,
Cloudflare Workers, Node, and Deno chimes,
"Not browsers!" it cries with delight,
Filtering server-side impostors right,
Now detection runs true, with regex just right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: excluding server runtimes from the worker navigator fallback, which matches the core objective of preventing server-side worker environments from incorrectly passing browser validation checks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[changeset-bot]

🦋 Changeset detected

Latest commit: fe6f0af

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

This PR includes changesets to release 21 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: fe6f0af

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-12T04:02:15.252Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

Note
Break Check could not snapshot 1 subpath; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on fe6f0af.}

[tmilewski]

Good catch