Communitygithub.com

deangilmoreremix/videoremix.vip2

Autenticación de extensión de Chrome con @clerk/chrome-extension: configuración de popup/sidepanel, syncHost para OAuth/SAML vía aplicación web, createClerkClient para service workers y extensiones headless, ID CRX estable. Se activa en: autenticación de extensión de Chrome, Plasmo clerk, inicio de sesión en popup, syncHost, token de service worker en segundo plano, createClerkClient, extensión headless.

¿Qué es videoremix.vip2?

Este skill proporciona guías completas y mejores prácticas para integrar Clerk (un servicio de autenticación y gestión de usuarios) en extensiones de Chrome, ya sea que uses Plasmo, popups, side panels, service workers o extensiones headless. Cubre desde la configuración básica con ClerkProvider hasta patrones avanzados como syncHost para delegar OAuth/SAML a una aplicación web, createClerkClient para entornos sin React (service workers, scripts de contenido) y el manejo de un ID CRX estable para evitar que la autenticación se rompa tras cada compilación. Incluye advertencias sobre limitaciones críticas (por ejemplo, OAuth no funciona en popups, los enlaces mágicos fallan en popups, los side panels no actualizan el estado de autenticación automáticamente) y soluciones detalladas para cada caso, incluyendo caché de tokens con chrome.storage. Es útil para desarrolladores de extensiones que necesitan autenticación robusta, soporte para múltiples métodos de inicio de sesión y sincronización con una aplicación web.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Patrones de Extensión de Chrome

REGLAS CRÍTICAS

  1. OAuth (Google, GitHub, etc.) y SAML NO son compatibles en popups o side panels: usa syncHost para delegar la autenticación a tu aplicación web
  2. 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
  3. 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
  4. Los service workers y scripts de contenido NO tienen acceso a los hooks de React de Clerk: usa createClerkClient() o paso de mensajes
  5. Las URL de extensión usan chrome-extension:// no http://: todas las URL de redirección deben usar chrome.runtime.getURL('.')
  6. Sin un ID CRX estable, cada recompilación rompe la autenticación: configura key en el manifest ANTES de implementar
  7. Los scripts de contenido no pueden usar Clerk directamente debido a restricciones de origen: Clerk aplica orígenes permitidos estrictos
  8. 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étodoPopupSide PanelsyncHost (con aplicación web)
Correo electrónico + OTPSíSíSí
Correo electrónico + EnlaceNoNoSí
Correo electrónico + ContraseñaSíSíSí
Nombre de usuario + ContraseñaSíSíSí
SMS + OTPSíSíSí
OAuth (Google, GitHub, etc.)NONOSÍ
SAMLNONOSÍ
PasskeysSíSíSí
Google One TapNoNoSí
Web3NoNoSí

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

  1. Visita Plasmo Itero Generate Keypairs
  2. 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ÁmbitoSe limpia al
chrome.storage.localDispositivoDesinstalación o limpieza manual
chrome.storage.sessionSesiónCierre del navegador
chrome.storage.syncTodos los dispositivosDesinstalación (limitado en tamaño, 8KB)
localStorageSolo popupCierre del popup: no usar para autenticación

Errores Comunes

SíntomaCausaSolución
Bucle de redirección al iniciar sesiónFalta URL de CRX en propiedades de ClerkProviderEstablece afterSignOutUrl, signInFallbackRedirectUrl
Botón de OAuth no funcionaOAuth no es compatible en popupUsa syncHost para delegar a la aplicación web
Estado de autenticación obsoleto después de iniciar sesión en la aplicación websyncHost no configuradoAgrega propiedad syncHost + host_permissions
El side panel muestra cerrado sesión después del inicio de sesión webLimitación conocidaEl usuario debe cerrar y volver a abrir el side panel
El background no puede obtener token después de 60 segundosSesión caducada, sin actualización en segundo planoUsa createClerkClient({ background: true })
El script de contenido no puede acceder a ClerkMundo aislado + restricciones de origenUsa paso de mensajes al service worker en segundo plano
La autenticación se rompe después de recompilarID CRX rotadoConfigura clave estable mediante .env.chrome
Variable PLASMO_PUBLIC_ indefinidaArchivo de entorno incorrectoUsa .env.development, no .env
Errores de protección contra botsCloudflare no es compatible en extensionesDesactiva la protección contra bots en el Panel de Control de Clerk
Caché de tokens no persisteUsando localStorage en el popupUsa chrome.storage.local o pasa la propiedad tokenCache

Requisitos de Plan

CaracterísticaPlan
Autenticación básica en popup (correo/contraseña, OTP)Gratuito
PasskeysGratuito
syncHostRequiere Pro (dominio personalizado)
OAuth a través de syncHostPro + OAuth configurado en la aplicación web
SAML a través de syncHostEnterprise
Protección contra botsN/A: debe estar desactivada para extensiones

Véase También

  • clerk-setup: Instalación inicial de Clerk
  • clerk-custom-ui: Flujos personalizados y apariencia

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 relacionados