clerk-chrome-extension-patterns

SKILL.md

Chrome Extension Patterns

CRITICAL RULES

OAuth (Google, GitHub, etc.) and SAML are NOT supported in popups or side panels -- use syncHost to delegate auth to your web app

Email links (magic links) don't work in popups -- the popup closes when the user clicks outside, resetting sign-in state

Side panels don't auto-refresh auth state -- users must close and reopen the side panel after signing in via the web app

Service workers and content scripts have NO access to Clerk React hooks -- use createClerkClient() or message passing

Extension URLs use chrome-extension:// not http:// -- all redirect URLs must use chrome.runtime.getURL('.')

Without a stable CRX ID, every rebuild breaks auth -- configure key in manifest BEFORE deploying

Content scripts cannot use Clerk directly due to origin restrictions -- Clerk enforces strict allowed origins

Bot protection must be DISABLED in Clerk Dashboard -- Cloudflare bot detection is not supported in extension environments

Authentication Options