Padrões de Extensão Chrome
REGRAS CRÍTICAS
- OAuth (Google, GitHub, etc.) e SAML NÃO são suportados em popups ou side panels — use
syncHostpara delegar autenticação à sua aplicação web - Links de email (magic links) não funcionam em popups — o popup fecha quando o usuário clica fora, resetando o estado de login
- 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
- Service workers e content scripts NÃO têm acesso aos hooks React do Clerk — use
createClerkClient()ou passagem de mensagens - URLs de extensão usam
chrome-extension://nãohttp://— todas as URLs de redirecionamento devem usarchrome.runtime.getURL('.') - Sem um ID CRX estável, cada reconstrução quebra a autenticação — configure
keyno manifesto ANTES de implantar - Content scripts não podem usar o Clerk diretamente devido a restrições de origem — o Clerk impõe origens permitidas estritas
- 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étodo | Popup | Side Panel | syncHost (com aplicação web) |
|---|---|---|---|
| Email + OTP | Sim | Sim | Sim |
| Email + Link | Não | Não | Sim |
| Email + Senha | Sim | Sim | Sim |
| Usuário + Senha | Sim | Sim | Sim |
| SMS + OTP | Sim | Sim | Sim |
| OAuth (Google, GitHub, etc.) | NÃO | NÃO | SIM |
| SAML | NÃO | NÃO | SIM |
| Chaves de acesso | Sim | Sim | Sim |
| Google One Tap | Não | Não | Sim |
| Web3 | Não | Não | Sim |
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):
- Visite Plasmo Itero Generate Keypairs
- 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 armazenamento | Escopo | Limpa em |
|---|---|---|
chrome.storage.local | Dispositivo | Desinstalação ou limpeza manual |
chrome.storage.session | Sessão | Fechamento do navegador |
chrome.storage.sync | Todos os dispositivos | Desinstalação (limitado em tamanho, 8KB) |
localStorage | Apenas popup | Fechamento do popup — não use para autenticação |
Problemas Comuns
| Sintoma | Causa | Correção |
|---|---|---|
| Loop de redirecionamento no login | URL CRX ausente nas props do ClerkProvider | Defina afterSignOutUrl, signInFallbackRedirectUrl |
| Botão OAuth não funciona | OAuth não suportado em popup | Use syncHost para delegar à aplicação web |
| Estado de autenticação desatualizado após login na aplicação web | syncHost não configurado | Adicione a prop syncHost + host_permissions |
| Side panel mostra como desconectado após login na web | Limitação conhecida | O usuário deve fechar e reabrir o side panel |
| Background não consegue obter token após 60s | Sessão expirou, sem atualização em background | Use createClerkClient({ background: true }) |
| Content script não consegue acessar Clerk | Mundo isolado + restrições de origem | Use passagem de mensagens para o service worker de fundo |
| Autenticação quebra após reconstrução | ID CRX rotacionado | Configure chave estável via .env.chrome |
Variável PLASMO_PUBLIC_ indefinida | Arquivo .env errado | Use .env.development, não .env |
| Erros de proteção contra bots | Cloudflare não suportado em extensões | Desative a proteção contra bots no Painel do Clerk |
| Cache de token não persiste | Usando localStorage em popup | Use chrome.storage.local ou passe a prop tokenCache |
Requisitos de Plano
| Funcionalidade | Plano |
|---|---|
| Autenticação básica em popup (email/senha, OTP) | Grátis |
| Chaves de acesso | Grátis |
| syncHost | Requer Pro (domínio personalizado) |
| OAuth via syncHost | Pro + OAuth configurado na aplicação web |
| SAML via syncHost | Enterprise |
| Proteção contra bots | N/D — deve estar desativada para extensões |
Veja Também
clerk-setup- Instalação inicial do Clerkclerk-custom-ui- Fluxos personalizados e aparência