clerk-js: "capacitor:" missing from the navigate() protocol allow-list, breaking Clerk in Capacitor iOS apps

[mehru9219]

Summary

Clerk.navigate() validates the protocol of every internal navigation against a hardcoded allow-list that includes wails: and chrome-extension: but not capacitor:. As a result, Clerk is unusable in a Capacitor iOS app: every relative navigation is rewritten to /, which breaks sign-in.

The code

From the shipped clerk.browser.js v5 (module 55809):

let r = ["http:", "https:", "wails:", "chrome-extension:"];

and in Clerk.navigate:

let i = new URL(e, window.location.href);
this.#N.includes(i.protocol) || (
  console.warn(`Clerk: "${i.protocol}" is not a valid protocol. Redirecting to "/" instead. ...`),
  i = new URL("/", window.location.href)
);

Why this breaks Capacitor specifically

Capacitor's iOS WebView serves bundled content from a custom scheme — capacitor://localhost by default. iosScheme cannot be set to http/https, because WKWebView reserves them (Capacitor docs, and Apple's setURLSchemeHandler documentation).

Because the target is resolved with new URL(e, window.location.href), every relative navigation on that origin returns protocol capacitor:, fails the check, and is rewritten to /.

Observed on device:

⚡️ [warn] - Clerk: "capacitor:" is not a valid protocol. Redirecting to "/" instead.

fired twice — once during initialisation and once mid sign-in. User-visible symptom: the email verification screen appears and is immediately replaced by the sign-up route, so sign-in can never complete.

Not fixable by configuration

signInUrl, signUpUrl, forceRedirectUrl, fallbackRedirectUrl etc. all supply relative paths, which is exactly what resolves to the rejected protocol. Supplying absolute https:// URLs passes the check but navigates the WebView out of the app, which is worse.

Proposed fix

Add "capacitor:" to the list. Clerk's docs already name Capacitor.js as a supported browser-like stack for allowed_origins, and wails: / chrome-extension: establish the precedent for embedded-shell schemes.

- let r = ["http:", "https:", "wails:", "chrome-extension:"];
+ let r = ["http:", "https:", "wails:", "chrome-extension:", "capacitor:"];

Ideally the list would also be extensible via ClerkOptions, so custom iosScheme values (Capacitor allows any non-reserved scheme) are supported without another release.

Current workaround

Setting iosScheme: 'wails' in capacitor.config.ts, so the origin becomes wails://localhost and satisfies the existing list. It works, but borrowing another framework's scheme name is obviously not intended usage.

Environment

• @clerk/clerk-react 5.35.3, @clerk/types 4.68.0, clerk-js v5 (hot-loaded)
• Capacitor 8, iOS

[wobsoriano]

Thanks for the detailed report!

Good news first. The protocol list is already extensible, exactly as you suggested. As of clerk-js 6.23.0 there's an allowedRedirectProtocols option you can pass to ClerkProvider:

<ClerkProvider publishableKey={...} allowedRedirectProtocols={['capacitor:']}>

This also covers custom iosScheme values. The version you're on (@clerk/clerk-react 5.x, which loads clerk-js v5) predates this option, which is why your bundle shows the hardcoded list. Upgrading to @clerk/react v6 will get you this, so no need for the iosScheme: 'wails' workaround.

That said, I want to be upfront that Capacitor isn't something Clerk officially supports. There's no Capacitor SDK, and running clerk-js inside a Capacitor app has problems that go deeper than this allow-list. If you'd like official support, you can upvote it here: https://feedback.clerk.com/request?id=8542c915-22c7-4130-8ebe-f68270d4aab8

The bigger problem is that sessions don't stick. Clerk keeps you signed in using cookies, and because your app runs on capacitor://localhost while Clerk's API lives on a different domain, iOS treats those cookies as third-party and blocks them. So even with navigation fixed, you may sign in successfully and then lose the session shortly after.

If you want to keep going with Capacitor, you'll also need this setup on your Clerk instance

1. Enable the Native API in the Dashboard under Native applications.
2. Add capacitor://localhost to your allowed origins. This is done through the Backend API with your secret key, since production instances reject unknown origins.
3. If you redirect back into the app with a custom scheme like myapp://oauth-callback, add that URL to the "Allowlist for mobile SSO redirect" under Native applications. It won't work in allowed origins.

Since you're already building in React, the path we'd actually recommend is @clerk/expo with Expo / React Native. It's our officially supported way to ship a native mobile app with React, it stores sessions in secure native storage instead of WebView cookies (so none of the issues above apply), and it includes native prebuilt components along with all the hooks you're using today.