Communitygithub.com

deangilmoreremix/videoremix.vip2

Autenticação de Extensão Chrome com @clerk/chrome-extension -- configuração de popup/sidepanel, syncHost para OAuth/SAML via aplicação web, createClerkClient para service workers e extensões headless, ID CRX estável.

O que é videoremix.vip2?

Este skill fornece um guia completo e padronizado para integrar autenticação Clerk em extensões Chrome, cobrindo popups, side panels, service workers e extensões headless. Ele explica as limitações críticas de cada ambiente (como OAuth não funcionar em popups) e oferece soluções como `syncHost` para delegar autenticação OAuth/SAML para uma aplicação web, e `createClerkClient()` com `background: true` para manter sessões ativas em service workers. O documento inclui exemplos práticos de código para Plasmo, configuração de variáveis de ambiente, permissões de manifesto, e um checklist de pitfalls comuns. Suporta Clerk + Chrome Extensions (incluindo Plasmo), com ênfase em IDs CRX estáveis e cache de tokens.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Padrões de Extensão Chrome

REGRAS CRÍTICAS

  1. OAuth (Google, GitHub, etc.) e SAML NÃO são suportados em popups ou side panels — use syncHost para delegar autenticação à sua aplicação web
  2. Links de email (magic links) não funcionam em popups — o popup fecha quando o usuário clica fora, resetando o estado de login
  3. Side panels não atualizam automaticamente o estado de autenticação — os usuários devem fechar e reabrir o side panel após fazer login via aplicação web
  4. Service workers e content scripts NÃO têm acesso aos hooks React do Clerk — use createClerkClient() ou passagem de mensagens
  5. URLs de extensão usam chrome-extension:// não http:// — todas as URLs de redirecionamento devem usar chrome.runtime.getURL('.')
  6. Sem um ID CRX estável, cada reconstrução quebra a autenticação — configure key no manifesto ANTES de implantar
  7. Content scripts não podem usar o Clerk diretamente devido a restrições de origem — o Clerk impõe origens permitidas estritas
  8. A proteção contra bots deve ser DESATIVADA no Painel do Clerk — a detecção de bots do Cloudflare não é suportada em ambientes de extensão

Opções de Autenticação

MétodoPopupSide PanelsyncHost (com aplicação web)
Email + OTPSimSimSim
Email + LinkNãoNãoSim
Email + SenhaSimSimSim
Usuário + SenhaSimSimSim
SMS + OTPSimSimSim
OAuth (Google, GitHub, etc.)NÃONÃOSIM
SAMLNÃONÃOSIM
Chaves de acessoSimSimSim
Google One TapNãoNãoSim
Web3NãoNãoSim

Início Rápido (Plasmo)

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

Habilite Native API no Painel do Clerk em Native applications. Necessário para todas as integrações de extensão.

.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

Use mode="modal" para SignInButton — navegar para uma página separada quebra o fluxo do popup.

syncHost — Sincronizar Autenticação com Aplicação Web

Use isso quando precisar de OAuth, SAML, ou quando quiser que a extensão reflita o login da sua aplicação web.

Como funciona: A extensão lê o cookie de sessão do Clerk do domínio da sua aplicação web via host_permissions.

Passo 1 — Variáveis de ambiente:

.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

Passo 2 — Adicione a prop 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 })}
>

Passo 3 — Configure host_permissions no package.json:

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

Passo 4 — Adicione o ID da extensão às origens permitidas da aplicação web via API do Clerk:

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"]}'

Oculte métodos de autenticação não suportados no popup ao usar syncHost:

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

Guia completo: references/sync-host.md

createClerkClient() para Vanilla JS / Service Workers

Importe de @clerk/chrome-extension/client (não de @clerk/chrome-extension).

Service worker de fundo (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
})

A flag background: true mantém as sessões atualizadas mesmo quando o popup/sidepanel está fechado. Sem ela, os tokens expiram após 60 segundos.

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

Guia completo: references/create-clerk-client.md

Extensão Headless (sem popup, sem side panel)

Para extensões que rodam inteiramente em segundo plano e sincronizam com uma aplicação web.

Usa syncHost + createClerkClient com background: true para ler o estado de autenticação dos cookies da aplicação 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
}

Requer host_permissions para o domínio do sync host no package.json.

Guia completo: references/headless-extension.md

Content Scripts

Content scripts rodam em um mundo JavaScript isolado injetado em páginas web. O Clerk não pode ser usado diretamente — restrições de origem impedem.

Use passagem de mensagens para solicitar estado de autenticação ao service worker de fundo:

// 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
  // use token for authenticated API calls
}

main()

Guia completo: references/content-scripts.md

ID CRX Estável

Sem uma chave fixa, o Chrome deriva o ID CRX de uma chave aleatória no momento da compilação. Isso rotaciona a cada reconstrução, quebrando as origens permitidas.

Opção A — Plasmo Itero (recomendado):

  1. Visite Plasmo Itero Generate Keypairs
  2. Clique em "Generate KeyPairs" — salve a Chave Privada com segurança, copie a Chave Pública e o ID CRX

Opção B — OpenSSL:

openssl genrsa -out key.pem 2048
# Use Plasmo Itero para converter ou extrair a chave pública no formato correto

.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/*"
    ]
  }
}

Adicione chrome-extension://YOUR_STABLE_CRX_ID no Painel do Clerk > Allowed Origins.

Cache de Token (persistir entre fechamentos de 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}>
Tipo de armazenamentoEscopoLimpa em
chrome.storage.localDispositivoDesinstalação ou limpeza manual
chrome.storage.sessionSessãoFechamento do navegador
chrome.storage.syncTodos os dispositivosDesinstalação (limitado em tamanho, 8KB)
localStorageApenas popupFechamento do popup — não use para autenticação

Problemas Comuns

SintomaCausaCorreção
Loop de redirecionamento no loginURL CRX ausente nas props do ClerkProviderDefina afterSignOutUrl, signInFallbackRedirectUrl
Botão OAuth não funcionaOAuth não suportado em popupUse syncHost para delegar à aplicação web
Estado de autenticação desatualizado após login na aplicação websyncHost não configuradoAdicione a prop syncHost + host_permissions
Side panel mostra como desconectado após login na webLimitação conhecidaO usuário deve fechar e reabrir o side panel
Background não consegue obter token após 60sSessão expirou, sem atualização em backgroundUse createClerkClient({ background: true })
Content script não consegue acessar ClerkMundo isolado + restrições de origemUse passagem de mensagens para o service worker de fundo
Autenticação quebra após reconstruçãoID CRX rotacionadoConfigure chave estável via .env.chrome
Variável PLASMO_PUBLIC_ indefinidaArquivo .env erradoUse .env.development, não .env
Erros de proteção contra botsCloudflare não suportado em extensõesDesative a proteção contra bots no Painel do Clerk
Cache de token não persisteUsando localStorage em popupUse chrome.storage.local ou passe a prop tokenCache

Requisitos de Plano

FuncionalidadePlano
Autenticação básica em popup (email/senha, OTP)Grátis
Chaves de acessoGrátis
syncHostRequer Pro (domínio personalizado)
OAuth via syncHostPro + OAuth configurado na aplicação web
SAML via syncHostEnterprise
Proteção contra botsN/D — deve estar desativada para extensões

Veja Também

  • clerk-setup - Instalação inicial do Clerk
  • clerk-custom-ui - Fluxos personalizados e aparência

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

Habilidades Relacionadas