clerk-chrome-extension-patterns

# Chrome Extension Patterns ## CRITICAL RULES 1. OAuth (Google, GitHub, etc.) and SAML are NOT supported in popups or side panels -- use `syncHost` to delegate auth to your web app 2. Email links (magic links) don't work in popups -- the popup closes when the user clicks outside, resetting sign-in state 3. Side panels don't auto-refresh auth state -- users must close and reopen the side panel after signing in via the web app 4. Service workers and content scripts have NO access to Clerk React hooks -- use `createClerkClient()` or message passing 5. Extension URLs use `chrome-extension://` not `http://` -- all redirect URLs must use `chrome.runtime.getURL('.')` 6. Without a stable CRX ID, every rebuild breaks auth -- configure `key` in manifest BEFORE deploying 7. Content scripts cannot use Clerk directly due to origin restrictions -- Clerk enforces strict allowed origins 8. Bot protection must be DISABLED in Clerk Dashboard -- Cloudflare bot detection is not supported in extension environments ## Authentication Options | Method | Popup | Side Panel | syncHost (with web app) | |--------|-------|------------|------------------------| | Email + OTP | Yes | Yes | Yes | | Email + Link | No | No | Yes | | Email + Password | Yes | Yes | Yes | | Username + Password | Yes | Yes | Yes | | SMS + OTP | Yes | Yes | Yes | | OAuth (Google, GitHub, etc.) | **NO** | **NO** | **YES** | | SAML | **NO** | **NO** | **YES** | | Passkeys | Yes | Yes | Yes | | Google One Tap | No | No | Yes | | ...