Communitygithub.com

deangilmoreremix/videoremix.vip2

Chrome-Erweiterung mit @clerk/chrome-extension – Einrichtung von Popup/Sidepanel, syncHost für OAuth/SAML über eine Web-App, createClerkClient für Service Worker und headless Erweiterungen, stabile CRX-ID.

Was ist videoremix.vip2?

Diese Skill beschreibt alle relevanten Muster und Best Practices für die Integration der Clerk-Authentifizierung in Chrome-Erweiterungen, einschließlich Popup, Side Panel, Background Service Worker und Content Scripts. Sie behandelt kritische Einschränkungen wie die fehlende Unterstützung von OAuth/SAML in Popups – daher muss `syncHost` verwendet werden, um die Authentifizierung an eine Web-App zu delegieren. Für Service Worker und headless Erweiterungen wird `createClerkClient()` mit dem Flag `background: true` empfohlen. Zudem wird erklärt, wie Content Scripts über Message Passing mit dem Background Worker kommunizieren können, da Clerk aufgrund von Origin-Restriktionen nicht direkt in Content Scripts genutzt werden kann. Eine stabile CRX-ID (z. B. mit Plasmo Itero generiert) und die korrekte Konfiguration von `key` und `host_permissions` sind unerlässlich, damit die Authentifizierung auch nach einem Rebuild nicht bricht. Die Skill behandelt außerdem Token-Caching, häufige Fehlerquellen und zeigt für jedes Feature den benötigten Clerk-Plan. Sie unterstützt die Plattformen Plasmo (React/Popup/Sidepanel/Background) und Vanilla-JS-Erweiterungen über `createClerkClient`.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Chrome-Erweiterungs-Muster

KRITISCHE REGELN

  1. OAuth (Google, GitHub usw.) und SAML werden in Popups oder Sidepanels NICHT unterstützt – verwenden Sie syncHost, um die Authentifizierung an Ihre Web-App zu delegieren
  2. E-Mail-Links (Magic Links) funktionieren nicht in Popups – das Popup schließt, wenn der Nutzer außerhalb klickt, und setzt den Anmeldestatus zurück
  3. Side-Panels aktualisieren den Authentifizierungsstatus nicht automatisch – Nutzer müssen das Side-Panel nach der Anmeldung über die Web-App schließen und erneut öffnen
  4. Service Worker und Content Scripts haben KEINEN Zugriff auf Clerk React Hooks – verwenden Sie createClerkClient() oder Message Passing
  5. Erweiterungs-URLs verwenden chrome-extension://, nicht http:// – alle Weiterleitungs-URLs müssen chrome.runtime.getURL('.') verwenden
  6. Ohne eine stabile CRX-ID bricht die Authentifizierung bei jedem Neubau – konfigurieren Sie den key im Manifest VOR dem Deployment
  7. Content Scripts können Clerk aufgrund von Origin-Restriktionen nicht direkt nutzen – Clerk erzwingt strenge erlaubte Ursprünge
  8. Bot-Schutz muss im Clerk-Dashboard DEAKTIVIERT werden – Cloudflare Bot Detection wird in Erweiterungsumgebungen nicht unterstützt

Authentifizierungsoptionen

MethodePopupSide PanelsyncHost (mit Web-App)
E-Mail + OTPJaJaJa
E-Mail + LinkNeinNeinJa
E-Mail + PasswortJaJaJa
Benutzername + PasswortJaJaJa
SMS + OTPJaJaJa
OAuth (Google, GitHub usw.)NEINNEINJA
SAMLNEINNEINJA
PasskeysJaJaJa
Google One TapNeinNeinJa
Web3NeinNeinJa

Schnellstart (Plasmo)

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

Aktivieren Sie die Native API im Clerk-Dashboard unter „Native applications“. Erforderlich für alle Erweiterungsintegrationen.

.env.development:

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-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('Missing PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY')
}

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

Verwenden Sie mode="modal" für SignInButton – die Navigation zu einer separaten Seite unterbricht den Popup-Flow.

syncHost – Authentifizierung mit der Web-App synchronisieren

Verwenden Sie dies, wenn Sie OAuth, SAML benötigen oder die Erweiterung den Anmeldestatus Ihrer Web-App widerspiegeln soll.

So funktioniert es: Die Erweiterung liest das Clerk-Sitzungscookie von der Domain Ihrer Web-App über host_permissions.

Schritt 1 – Umgebungsvariablen:

.env.development:

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-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.your-domain.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.your-domain.com

Schritt 2 – syncHost-Prop hinzufügen:

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 })}
>

Schritt 3 – host_permissions in package.json konfigurieren:

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

Schritt 4 – Erweiterungs-ID zu den erlaubten Ursprüngen der Web-App über die Clerk-API hinzufügen:

curl -X PATCH https://api.clerk.com/v1/instance \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-type: application/json" \
  -d '{"allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID"]}'

Nicht unterstützte Authentifizierungsmethoden im Popup bei Verwendung von syncHost ausblenden:

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

Vollständige Anleitung: references/sync-host.md

createClerkClient() für Vanilla-JS / Service Worker

Import aus @clerk/chrome-extension/client (nicht aus @clerk/chrome-extension).

Background Service Worker (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] Error:', JSON.stringify(error))
      sendResponse({ token: null })
    })
  return true
})

Das Flag background: true hält Sitzungen frisch, auch wenn Popup/Sidepanel geschlossen sind. Ohne es laufen Token nach 60 Sekunden ab.

Popup mit 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()
})

Vollständige Anleitung: references/create-clerk-client.md

Headless-Erweiterung (kein Popup, kein Sidepanel)

Für Erweiterungen, die vollständig im Hintergrund laufen und mit einer Web-App synchronisieren.

Verwendet syncHost + createClerkClient mit background: true, um den Authentifizierungsstatus aus den Cookies der Web-App zu lesen.

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
}

Erfordert host_permissions für die Sync-Host-Domain in package.json.

Vollständige Anleitung: references/headless-extension.md

Content Scripts

Content Scripts laufen in einer isolierten JavaScript-Welt, die in Webseiten eingefügt wird. Clerk kann nicht direkt verwendet werden – Origin-Restriktionen verhindern dies.

Verwenden Sie Message Passing, um den Authentifizierungsstatus vom Background Service Worker anzufordern:

// 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
  // Token für authentifizierte API-Aufrufe verwenden
}

main()

Vollständige Anleitung: references/content-scripts.md

Stabile CRX-ID

Ohne einen festen Schlüssel leitet Chrome die CRX-ID von einem zufälligen Schlüssel zur Build-Zeit ab. Dieser wechselt bei jedem Neubau, wodurch erlaubte Ursprünge brechen.

Option A – Plasmo Itero (empfohlen):

  1. Besuchen Sie Plasmo Itero Generate Keypairs
  2. Klicken Sie auf „Generate KeyPairs“ – speichern Sie den privaten Schlüssel sicher, kopieren Sie den öffentlichen Schlüssel und die CRX-ID

Option B – OpenSSL:

openssl genrsa -out key.pem 2048
# Verwenden Sie Plasmo Itero, um den öffentlichen Schlüssel im richtigen Format zu konvertieren oder zu extrahieren

.env.chrome:

CRX_PUBLIC_KEY="<PUBLIC KEY from Itero>"

package.json:

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

Fügen Sie chrome-extension://YOUR_STABLE_CRX_ID im Clerk-Dashboard unter „Allowed Origins“ hinzu.

Token-Cache (über Popup-Schließen hinweg persistent)

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}>
SpeichertypGeltungsbereichWird gelöscht bei
chrome.storage.localGerätDeinstallation oder manuelles Löschen
chrome.storage.sessionSitzungSchließen des Browsers
chrome.storage.syncAlle GeräteDeinstallation (größenbegrenzt, 8KB)
localStorageNur PopupPopup schließen – nicht für Authentifizierung verwenden

Häufige Fallstricke

SymptomUrsacheLösung
Weiterleitungsschleife bei AnmeldungFehlende CRX-URL in ClerkProvider-PropsafterSignOutUrl, signInFallbackRedirectUrl setzen
OAuth-Button funktioniert nichtOAuth wird im Popup nicht unterstütztsyncHost verwenden, um an Web-App zu delegieren
Auth-Status nach Web-App-Anmeldung veraltetsyncHost nicht konfiguriertsyncHost-Prop + host_permissions hinzufügen
Sidepanel zeigt nach Web-Anmeldung „abgemeldet“Bekannte EinschränkungBenutzer muss Sidepanel schließen und erneut öffnen
Hintergrund kann nach 60 Sekunden kein Token abrufenSitzung abgelaufen, kein Hintergrund-RefreshcreateClerkClient({ background: true }) verwenden
Content Script kann nicht auf Clerk zugreifenIsolierte Welt + Origin-RestriktionenMessage Passing zum Background Service Worker verwenden
Authentifizierung bricht nach NeubauCRX-ID rotiertStabilen Schlüssel über .env.chrome konfigurieren
PLASMO_PUBLIC_-Variable undefiniertFalsche Umgebungsdatei.env.development verwenden, nicht .env
Bot-Schutz-FehlerCloudflare wird in Erweiterungen nicht unterstütztBot-Schutz im Clerk-Dashboard deaktivieren
Token-Cache nicht persistentVerwendung von localStorage im Popupchrome.storage.local oder tokenCache-Prop verwenden

Plananforderungen

FunktionPlan
Einfache Popup-Authentifizierung (E-Mail/Passwort, OTP)Kostenlos
PasskeysKostenlos
syncHostErfordert Pro (benutzerdefinierte Domain)
OAuth über syncHostPro + OAuth in Web-App konfiguriert
SAML über syncHostEnterprise
Bot-SchutzN/V – muss für Erweiterungen deaktiviert werden

Siehe auch

  • clerk-setup – Erste Clerk-Installation
  • clerk-custom-ui – Benutzerdefinierte Abläufe und Erscheinungsbild

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

Verwandte Skills