clerk-chrome-extension-patterns

What problem does it solve?

Chrome extensions cannot run standard web-based identity provider redirects and have strict origin restrictions, which breaks common OAuth, SAML, and magic-link flows and makes session management fragile across popups, side panels, background workers, and content scripts. This Skill consolidates reliable patterns for integrating Clerk into Chrome extensions so extensions can obtain and refresh session tokens, delegate OAuth to a web app, and avoid rebuild-related auth breakage.

Core Features & Use Cases

• Popup & Sidepanel Integration: Wrap UI in ClerkProvider and use chrome.runtime.getURL for redirect URLs so sign-in and sign-out redirect flows work inside extension pages.
• syncHost Delegation: Delegate OAuth and SAML to your web app using syncHost, host_permissions, and allowed_origins to enable social login and magic links.
• Background & Headless Clients: Use createClerkClient with background:true in service workers to keep sessions fresh and provide tokens to content scripts via message passing.
• Stable Deployment & Token Caching: Pin a stable CRX ID in the manifest, configure a persistent token cache (chrome.storage.local), and disable incompatible bot protection to prevent auth failures.
• Use Case: A Plasmo-based extension that needs Google OAuth via a web app, background API calls on behalf of the user, and content-script overlays that require authenticated requests.

Quick Start

Add PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY and PLASMO_PUBLIC_CLERK_SYNC_HOST to your env files, wrap your popup with ClerkProvider using chrome.runtime.getURL for redirect props, and configure host_permissions plus a stable CRX key in the manifest.