Patrones de Extensión de Chrome
REGLAS CRÍTICAS
- OAuth (Google, GitHub, etc.) y SAML NO son compatibles en popups o side panels: usa
syncHostpara delegar la autenticación a tu aplicación web - Los enlaces por correo electrónico (magic links) no funcionan en popups: el popup se cierra cuando el usuario hace clic fuera, restableciendo el estado de inicio de sesión
- Los side panels no actualizan automáticamente el estado de autenticación: los usuarios deben cerrar y volver a abrir el side panel después de iniciar sesión a través de la aplicación web
- Los service workers y scripts de contenido NO tienen acceso a los hooks de React de Clerk: usa
createClerkClient()o paso de mensajes - Las URL de extensión usan
chrome-extension://nohttp://: todas las URL de redirección deben usarchrome.runtime.getURL('.') - Sin un ID CRX estable, cada recompilación rompe la autenticación: configura
keyen el manifest ANTES de implementar - Los scripts de contenido no pueden usar Clerk directamente debido a restricciones de origen: Clerk aplica orígenes permitidos estrictos
- La protección contra bots debe estar DESACTIVADA en el Panel de Control de Clerk: la detección de bots de Cloudflare no es compatible en entornos de extensión
Opciones de Autenticación
| Método | Popup | Side Panel | syncHost (con aplicación web) |
|---|---|---|---|
| Correo electrónico + OTP | Sí | Sí | Sí |
| Correo electrónico + Enlace | No | No | Sí |
| Correo electrónico + Contraseña | Sí | Sí | Sí |
| Nombre de usuario + Contraseña | Sí | Sí | Sí |
| SMS + OTP | Sí | Sí | Sí |
| OAuth (Google, GitHub, etc.) | NO | NO | SÍ |
| SAML | NO | NO | SÍ |
| Passkeys | Sí | Sí | Sí |
| Google One Tap | No | No | Sí |
| Web3 | No | No | Sí |
Inicio Rápido (Plasmo)
npx create-plasmo --with-tailwindcss --with-src my-extension
cd my-extension
npm install @clerk/chrome-extension
Habilita Native API en el Panel de Control de Clerk, en Aplicaciones nativas. Es necesario para todas las integraciones de extensiones.
.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('Falta 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
Usa mode="modal" para SignInButton: navegar a una página separada rompe el flujo del popup.
syncHost: Sincronizar Autenticación con la Aplicación Web
Úsalo cuando necesites OAuth, SAML o que la extensión refleje el inicio de sesión desde tu aplicación web.
Cómo funciona: La extensión lee la cookie de sesión de Clerk desde el dominio de tu aplicación web mediante host_permissions.
Paso 1: Variables de entorno:
.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
Paso 2: Agregar la propiedad 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 })}
>
Paso 3: Configurar host_permissions en package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Paso 4: Agregar el ID de extensión a los orígenes permitidos de la aplicación web mediante la API de Clerk:
curl -X PATCH https://api.clerk.com/v1/instance \
-H "Authorization: Bearer TU_CLAVE_SECRETA" \
-H "Content-type: application/json" \
-d '{"allowed_origins": ["chrome-extension://TU_ID_DE_EXTENSIÓN"]}'
Ocultar métodos de autenticación no compatibles en popup al usar syncHost:
<SignIn
appearance={{
elements: {
socialButtonsRoot: 'plasmo-hidden',
dividerRow: 'plasmo-hidden',
},
}}
/>
Guía completa: references/sync-host.md
createClerkClient() para Vanilla JS / Service Workers
Importa desde @clerk/chrome-extension/client (no desde @clerk/chrome-extension).
Service worker en segundo plano (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
})
El indicador background: true mantiene las sesiones actualizadas incluso cuando el popup/sidepanel está cerrado. Sin él, los tokens caducan después de 60 segundos.
Popup con 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()
})
Guía completa: references/create-clerk-client.md
Extensión Headless (sin popup, sin side panel)
Para extensiones que se ejecutan completamente en segundo plano y se sincronizan con una aplicación web.
Usa syncHost + createClerkClient con background: true para leer el estado de autenticación de las cookies de la aplicación 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
}
Requiere host_permissions para el dominio del host de sincronización en package.json.
Guía completa: references/headless-extension.md
Scripts de Contenido
Los scripts de contenido se ejecutan en un mundo JavaScript aislado inyectado en páginas web. Clerk no se puede usar directamente: las restricciones de origen lo impiden.
Usa paso de mensajes para solicitar el estado de autenticación al service worker en segundo plano:
// 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
// usa el token para llamadas API autenticadas
}
main()
Guía completa: references/content-scripts.md
ID CRX Estable
Sin una clave fija, Chrome deriva el ID CRX de una clave aleatoria en el momento de la compilación. Esto rota en cada recompilación, rompiendo los orígenes permitidos.
Opción A: Plasmo Itero (recomendado):
- Visita Plasmo Itero Generate Keypairs
- Haz clic en "Generate KeyPairs": guarda la Clave Privada de forma segura, copia la Clave Pública y el ID CRX
Opción B: OpenSSL:
openssl genrsa -out key.pem 2048
# Usa Plasmo Itero para convertir o extraer la clave pública en el formato correcto
.env.chrome:
CRX_PUBLIC_KEY="<CLAVE PÚBLICA de Itero>"
package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"http://localhost/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Agrega chrome-extension://TU_ID_CRX_ESTABLE en el Panel de Control de Clerk > Orígenes Permitidos.
Caché de Tokens (persistir al cerrar 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 almacenamiento | Ámbito | Se limpia al |
|---|---|---|
chrome.storage.local | Dispositivo | Desinstalación o limpieza manual |
chrome.storage.session | Sesión | Cierre del navegador |
chrome.storage.sync | Todos los dispositivos | Desinstalación (limitado en tamaño, 8KB) |
localStorage | Solo popup | Cierre del popup: no usar para autenticación |
Errores Comunes
| Síntoma | Causa | Solución |
|---|---|---|
| Bucle de redirección al iniciar sesión | Falta URL de CRX en propiedades de ClerkProvider | Establece afterSignOutUrl, signInFallbackRedirectUrl |
| Botón de OAuth no funciona | OAuth no es compatible en popup | Usa syncHost para delegar a la aplicación web |
| Estado de autenticación obsoleto después de iniciar sesión en la aplicación web | syncHost no configurado | Agrega propiedad syncHost + host_permissions |
| El side panel muestra cerrado sesión después del inicio de sesión web | Limitación conocida | El usuario debe cerrar y volver a abrir el side panel |
| El background no puede obtener token después de 60 segundos | Sesión caducada, sin actualización en segundo plano | Usa createClerkClient({ background: true }) |
| El script de contenido no puede acceder a Clerk | Mundo aislado + restricciones de origen | Usa paso de mensajes al service worker en segundo plano |
| La autenticación se rompe después de recompilar | ID CRX rotado | Configura clave estable mediante .env.chrome |
Variable PLASMO_PUBLIC_ indefinida | Archivo de entorno incorrecto | Usa .env.development, no .env |
| Errores de protección contra bots | Cloudflare no es compatible en extensiones | Desactiva la protección contra bots en el Panel de Control de Clerk |
| Caché de tokens no persiste | Usando localStorage en el popup | Usa chrome.storage.local o pasa la propiedad tokenCache |
Requisitos de Plan
| Característica | Plan |
|---|---|
| Autenticación básica en popup (correo/contraseña, OTP) | Gratuito |
| Passkeys | Gratuito |
| syncHost | Requiere Pro (dominio personalizado) |
| OAuth a través de syncHost | Pro + OAuth configurado en la aplicación web |
| SAML a través de syncHost | Enterprise |
| Protección contra bots | N/A: debe estar desactivada para extensiones |
Véase También
clerk-setup: Instalación inicial de Clerkclerk-custom-ui: Flujos personalizados y apariencia