Communitygithub.com

deangilmoreremix/videoremix.vip2

Authentification d'extension Chrome avec @clerk/chrome-extension — configuration du popup/sidepanel, syncHost pour OAuth/SAML via l'application web, createClerkClient pour les service workers et les extensions headless, ID CRX stable. Déclencheurs : authentification d'extension Chrome, Plasmo clerk, connexion popup, syncHost, jeton de service worker en arrière-plan, createClerkClient, extension headless.

Qu'est-ce que videoremix.vip2 ?

Cette compétence fournit un guide complet pour intégrer Clerk (une plateforme d'authentification) dans les extensions Chrome, en utilisant la bibliothèque `@clerk/chrome-extension`. Elle couvre plusieurs scénarios : l'authentification dans les popups et side panels, la synchronisation de l'état de connexion avec une application web via `syncHost` (nécessaire pour OAuth et SAML), l'utilisation de `createClerkClient()` pour les service workers et les scripts de contenu, ainsi que les extensions headless qui fonctionnent entièrement en arrière-plan. La compétence insiste sur les règles critiques propres aux extensions Chrome, comme l'impossibilité d'utiliser OAuth dans les popups, la nécessité d'un ID CRX stable pour éviter de casser l'authentification après chaque reconstruction, et l'utilisation du `message passing` pour les scripts de contenu. Elle fournit des exemples de code détaillés pour Plasmo, des configurations de variables d'environnement, et un tableau des pièges courants avec leurs solutions. Les plateformes supportées incluent les extensions Chrome avec React (Plasmo) et vanilla JS pour les service workers.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-chrome-extension-patterns

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Modèles d'authentification pour extensions Chrome

RÈGLES CRITIQUES

  1. OAuth (Google, GitHub, etc.) et SAML ne sont PAS pris en charge dans les popups ou side panels — utilisez syncHost pour déléguer l'authentification à votre application web
  2. Les liens par e-mail (magic links) ne fonctionnent pas dans les popups — le popup se ferme lorsque l'utilisateur clique à l'extérieur, réinitialisant l'état de connexion
  3. Les side panels ne mettent pas à jour automatiquement l'état d'authentification — les utilisateurs doivent fermer et rouvrir le side panel après s'être connectés via l'application web
  4. Les service workers et les scripts de contenu n'ont PAS accès aux hooks React de Clerk — utilisez createClerkClient() ou le passage de messages
  5. Les URLs d'extension utilisent chrome-extension:// et non http:// — toutes les URLs de redirection doivent utiliser chrome.runtime.getURL('.')
  6. Sans un ID CRX stable, chaque reconstruction brise l'authentification — configurez key dans le manifeste AVANT de déployer
  7. Les scripts de contenu ne peuvent pas utiliser Clerk directement en raison des restrictions d'origine — Clerk applique des origines autorisées strictes
  8. La protection anti-bot doit être DÉSACTIVÉE dans le tableau de bord Clerk — la détection de bot Cloudflare n'est pas prise en charge dans les environnements d'extension

Options d'authentification

MéthodePopupSide PanelsyncHost (avec application web)
E-mail + OTPOuiOuiOui
E-mail + LienNonNonOui
E-mail + Mot de passeOuiOuiOui
Nom d'utilisateur + Mot de passeOuiOuiOui
SMS + OTPOuiOuiOui
OAuth (Google, GitHub, etc.)NONNONOUI
SAMLNONNONOUI
PasskeysOuiOuiOui
Google One TapNonNonOui
Web3NonNonOui

Démarrage rapide (Plasmo)

npx create-plasmo --with-tailwindcss --with-src mon-extension
cd mon-extension
npm install @clerk/chrome-extension

Activez Native API dans le tableau de bord Clerk sous Applications natives. Requis pour toutes les intégrations d'extension.

.env.development :

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://votre-app.clerk.accounts.dev

src/popup.tsx :

import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from '@clerk/chrome-extension'

const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const EXTENSION_URL = chrome.runtime.getURL('.')

if (!PUBLISHABLE_KEY) {
  throw new Error('PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY manquant')
}

function IndexPopup() {
  return (
    <ClerkProvider
      publishableKey={PUBLISHABLE_KEY}
      afterSignOutUrl={`${EXTENSION_URL}/popup.html`}
      signInFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
      signUpFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
    >
      <Show when="signed-out">
        <SignInButton mode="modal" />
        <SignUpButton mode="modal" />
      </Show>
      <Show when="signed-in">
        <UserButton />
      </Show>
    </ClerkProvider>
  )
}

export default IndexPopup

Utilisez mode="modal" pour SignInButton — naviguer vers une page séparée brise le flux du popup.

syncHost — Synchroniser l'authentification avec l'application web

Utilisez ceci lorsque vous avez besoin d'OAuth, SAML, ou souhaitez que l'extension reflète la connexion depuis votre application web.

Comment ça fonctionne : L'extension lit le cookie de session Clerk du domaine de votre application web via host_permissions.

Étape 1 — Variables d'environnement :

.env.development :

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://votre-app.clerk.accounts.dev
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost

.env.production :

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_FRONTEND_API=https://clerk.votre-domaine.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.votre-domaine.com

Étape 2 — Ajoutez la propriété syncHost :

const SYNC_HOST = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST

<ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  syncHost={SYNC_HOST}
  afterSignOutUrl="/"
  routerPush={(to) => navigate(to)}
  routerReplace={(to) => navigate(to, { replace: true })}
>

Étape 3 — Configurez host_permissions dans package.json :

{
  "manifest": {
    "key": "$CRX_PUBLIC_KEY",
    "permissions": ["cookies", "storage"],
    "host_permissions": [
      "$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
      "$CLERK_FRONTEND_API/*"
    ]
  }
}

Étape 4 — Ajoutez l'ID de l'extension aux origines autorisées de l'application web via l'API Clerk :

curl -X PATCH https://api.clerk.com/v1/instance \
  -H "Authorization: Bearer VOTRE_CLÉ_SECRÈTE" \
  -H "Content-type: application/json" \
  -d '{"allowed_origins": ["chrome-extension://VOTRE_ID_EXTENSION"]}'

Masquez les méthodes d'authentification non prises en charge dans le popup lors de l'utilisation de syncHost :

<SignIn
  appearance={{
    elements: {
      socialButtonsRoot: 'plasmo-hidden',
      dividerRow: 'plasmo-hidden',
    },
  }}
/>

Guide complet : references/sync-host.md

createClerkClient() pour Vanilla JS / Service Workers

Importez depuis @clerk/chrome-extension/client (pas @clerk/chrome-extension).

Service worker d'arrière-plan (src/background/index.ts) :

import { createClerkClient } from '@clerk/chrome-extension/client'

const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY

async function getToken(): Promise<string | null> {
  const clerk = await createClerkClient({
    publishableKey,
    background: true,
  })
  if (!clerk.session) return null
  return await clerk.session.getToken()
}

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  getToken()
    .then((token) => sendResponse({ token }))
    .catch((error) => {
      console.error('[Background] Erreur :', JSON.stringify(error))
      sendResponse({ token: null })
    })
  return true
})

Le drapeau background: true maintient les sessions à jour même lorsque le popup/side panel est fermé. Sans lui, les jetons expirent après 60 secondes.

Popup avec vanilla JS (src/popup.ts) :

import { createClerkClient } from '@clerk/chrome-extension/client'

const EXTENSION_URL = chrome.runtime.getURL('.')
const POPUP_URL = `${EXTENSION_URL}popup.html`

const clerk = createClerkClient({ publishableKey })

clerk.load({
  afterSignOutUrl: POPUP_URL,
  signInForceRedirectUrl: POPUP_URL,
  signUpForceRedirectUrl: POPUP_URL,
  allowedRedirectProtocols: ['chrome-extension:'],
}).then(() => {
  clerk.addListener(render)
  render()
})

Guide complet : references/create-clerk-client.md

Extension Headless (sans popup, sans side panel)

Pour les extensions qui s'exécutent entièrement en arrière-plan et se synchronisent avec une application web.

Utilise syncHost + createClerkClient avec background: true pour lire l'état d'authentification depuis les cookies de l'application web.

import { createClerkClient } from '@clerk/chrome-extension/client'

const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const syncHost = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST

async function getAuthenticatedUser() {
  const clerk = await createClerkClient({
    publishableKey,
    syncHost,
    background: true,
  })
  return clerk.user
}

Nécessite host_permissions pour le domaine du sync host dans package.json.

Guide complet : references/headless-extension.md

Scripts de contenu

Les scripts de contenu s'exécutent dans un monde JavaScript isolé injecté dans les pages web. Clerk ne peut pas être utilisé directement — les restrictions d'origine l'empêchent.

Utilisez le passage de messages pour demander l'état d'authentification au service worker d'arrière-plan :

// content.ts
async function getToken(): Promise<string | null> {
  return new Promise((resolve) => {
    chrome.runtime.sendMessage({ type: 'GET_TOKEN' }, (response) => {
      resolve(response?.token ?? null)
    })
  })
}

async function main() {
  const token = await getToken()
  if (!token) return
  // utiliser le jeton pour des appels API authentifiés
}

main()

Guide complet : references/content-scripts.md

ID CRX Stable

Sans clé épinglée, Chrome dérive l'ID CRX d'une clé aléatoire lors de la construction. Cela tourne à chaque reconstruction, brisant les origines autorisées.

Option A — Plasmo Itero (recommandé) :

  1. Visitez Plasmo Itero Generate Keypairs
  2. Cliquez sur "Generate KeyPairs" — sauvegardez la clé privée en toute sécurité, copiez la clé publique et l'ID CRX

Option B — OpenSSL :

openssl genrsa -out key.pem 2048
# Utilisez Plasmo Itero pour convertir ou extraire la clé publique au bon format

.env.chrome:

CRX_PUBLIC_KEY="<CLÉ PUBLIQUE d'Itero>"

package.json:

{
  "manifest": {
    "key": "$CRX_PUBLIC_KEY",
    "permissions": ["cookies", "storage"],
    "host_permissions": [
      "http://localhost/*",
      "$CLERK_FRONTEND_API/*"
    ]
  }
}

Ajoutez chrome-extension://VOTRE_ID_CRX_STABLE dans le tableau de bord Clerk > Origines autorisées.

Cache de jetons (persister après la fermeture du popup)

const tokenCache = {
  async getToken(key: string) {
    const result = await chrome.storage.local.get(key)
    return result[key] ?? null
  },
  async saveToken(key: string, token: string) {
    await chrome.storage.local.set({ [key]: token })
  },
  async clearToken(key: string) {
    await chrome.storage.local.remove(key)
  },
}

<ClerkProvider publishableKey={PUBLISHABLE_KEY} tokenCache={tokenCache}>
Type de stockagePortéeEffacement
chrome.storage.localAppareilDésinstallation ou effacement manuel
chrome.storage.sessionSessionFermeture du navigateur
chrome.storage.syncTous les appareilsDésinstallation (limité en taille, 8 Ko)
localStoragePopup uniquementFermeture du popup — ne pas utiliser pour l'authentification

Pièges courants

SymptômeCauseCorrectif
Boucle de redirection lors de la connexionURL CRX manquante dans les propriétés de ClerkProviderDéfinissez afterSignOutUrl, signInFallbackRedirectUrl
Bouton OAuth ne fonctionne pasOAuth non pris en charge dans le popupUtilisez syncHost pour déléguer à l'application web
État d'authentification obsolète après connexion à l'application websyncHost non configuréAjoutez la propriété syncHost + host_permissions
Side panel affiche déconnecté après connexion webLimitation connueL'utilisateur doit fermer et rouvrir le side panel
L'arrière-plan ne peut pas obtenir de jeton après 60 sSession expirée, pas d'actualisation en arrière-planUtilisez createClerkClient({ background: true })
Le script de contenu ne peut pas accéder à ClerkMonde isolé + restrictions d'origineUtilisez le passage de messages au service worker d'arrière-plan
L'authentification se brise après reconstructionID CRX changéConfigurez une clé stable via .env.chrome
Variable PLASMO_PUBLIC_ non définieMauvais fichier d'environnementUtilisez .env.development, pas .env
Erreurs de protection anti-botCloudflare non pris en charge dans les extensionsDésactivez la protection anti-bot dans le tableau de bord Clerk
Le cache de jetons ne persiste pasUtilisation de localStorage dans le popupUtilisez chrome.storage.local ou passez la propriété tokenCache

Exigences du plan

FonctionnalitéPlan
Authentification popup de base (e-mail/mot de passe, OTP)Gratuit
PasskeysGratuit
syncHostNécessite Pro (domaine personnalisé)
OAuth via syncHostPro + OAuth configuré sur l'application web
SAML via syncHostEnterprise
Protection anti-botN/A — doit être désactivée pour les extensions

Voir aussi

  • clerk-setup — Installation initiale de Clerk
  • clerk-custom-ui — Flux personnalisés et apparence

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

Skills associés