Communitygithub.com

deangilmoreremix/videoremix.vip2

Chrome 확장 프로그램 인증 설정 — @clerk/chrome-extension을 사용한 팝업/사이드패널 구성, syncHost를 통한 OAuth/SAML 위임, 서비스 워커 및 헤드리스 확장을 위한 createClerkClient, 안정적인 CRX ID 관리.

videoremix.vip2란 무엇인가요?

이 기술은 Chrome 확장 프로그램(Plasmo 기반 포함)에서 Clerk 인증을 완전히 통합하는 방법을 설명합니다. 주요 포인트는 팝업이나 사이드패널에서 OAuth/SAML을 직접 지원하지 않으므로 syncHost를 통해 웹 앱에 인증을 위임해야 한다는 점, 서비스 워커와 콘텐츠 스크립트는 React 훅 대신 createClerkClient()를 사용해야 한다는 점, 확장 프로그램 ID가 변경되면 인증이 깨지므로 manifest에 안정적인 key를 설정해야 한다는 점입니다. 또한 토큰 캐시 지속성, 콘텐츠 스크립트에서 메시지 전달을 통한 인증 상태 요청, bot protection 비활성화 등 다양한 환경별 설정과 주의사항을 다룹니다. 이 문서는 Plasmo, Vanilla JS, 헤드리스 확장 등 여러 플랫폼을 지원하며, 실제 코드 예제와 함께 각 구성 요소의 역할과 상호작용을 명확히 제시합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Chrome 확장 프로그램 패턴

중요 규칙

  1. OAuth(Google, GitHub 등) 및 SAML은 팝업이나 사이드패널에서 지원되지 않습니다. syncHost를 사용하여 웹 앱에 인증을 위임하세요.
  2. 이메일 링크(매직 링크)는 팝업에서 작동하지 않습니다. 사용자가 팝업 외부를 클릭하면 팝업이 닫혀 로그인 상태가 초기화됩니다.
  3. 사이드패널은 인증 상태를 자동으로 새로 고치지 않습니다. 사용자는 웹 앱에서 로그인한 후 사이드패널을 닫았다가 다시 열어야 합니다.
  4. 서비스 워커와 콘텐츠 스크립트는 Clerk React 훅에 접근할 수 없습니다. createClerkClient() 또는 메시지 전달을 사용하세요.
  5. 확장 프로그램 URL은 chrome-extension://을 사용하며 http://를 사용하지 않습니다. 모든 리디렉션 URL은 chrome.runtime.getURL('.')을 사용해야 합니다.
  6. 안정적인 CRX ID가 없으면 빌드할 때마다 인증이 깨집니다. 배포 전에 manifest에 key를 설정하세요.
  7. 콘텐츠 스크립트는 출처 제한으로 인해 Clerk를 직접 사용할 수 없습니다. Clerk는 엄격한 허용 출처를 적용합니다.
  8. Clerk 대시보드에서 Bot protection을 비활성화해야 합니다. Cloudflare 봇 감지는 확장 프로그램 환경에서 지원되지 않습니다.

인증 옵션

방법팝업사이드패널syncHost (웹 앱 포함)
이메일 + OTP예예예
이메일 + 링크아니요아니요예
이메일 + 비밀번호예예예
사용자 이름 + 비밀번호예예예
SMS + OTP예예예
OAuth (Google, GitHub 등)아니요아니요예
SAML아니요아니요예
패스키예예예
Google One Tap아니요아니요예
Web3아니요아니요예

빠른 시작 (Plasmo)

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

Clerk 대시보드에서 Native API를 활성화합니다. 모든 확장 프로그램 통합에 필요합니다.

.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

SignInButton에 mode="modal"을 사용하세요. 별도 페이지로 이동하면 팝업 흐름이 깨집니다.

syncHost — 웹 앱과 인증 동기화

OAuth, SAML이 필요하거나 확장 프로그램이 웹 앱의 로그인 상태를 반영하도록 하려면 이 기능을 사용하세요.

작동 방식: 확장 프로그램이 host_permissions를 통해 웹 앱 도메인의 Clerk 세션 쿠키를 읽습니다.

1단계 — 환경 변수:

.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

2단계 — syncHost prop 추가:

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

3단계 — package.json에서 host_permissions 설정:

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

4단계 — Clerk API를 통해 웹 앱의 허용 출처에 확장 ID 추가:

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

syncHost 사용 시 팝업에서 지원되지 않는 인증 방법 숨기기:

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

전체 가이드: references/sync-host.md

createClerkClient() — Vanilla JS / 서비스 워커

@clerk/chrome-extension/client에서 가져옵니다(@clerk/chrome-extension이 아님).

백그라운드 서비스 워커 (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
})

background: true 플래그는 팝업/사이드패널이 닫혀도 세션을 새로 유지합니다. 이 플래그가 없으면 토큰이 60초 후에 만료됩니다.

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

전체 가이드: references/create-clerk-client.md

헤드리스 확장 프로그램 (팝업 없음, 사이드패널 없음)

백그라운드에서 완전히 실행되고 웹 앱과 동기화되는 확장 프로그램을 위한 것입니다.

syncHost + background: true와 함께 createClerkClient를 사용하여 웹 앱의 쿠키에서 인증 상태를 읽습니다.

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
}

package.json에서 sync 호스트 도메인에 대한 host_permissions가 필요합니다.

전체 가이드: references/headless-extension.md

콘텐츠 스크립트

콘텐츠 스크립트는 웹 페이지에 주입된 격리된 JavaScript 세계에서 실행됩니다. Clerk를 직접 사용할 수 없습니다 — 출처 제한으로 인해 사용이 불가능합니다.

메시지 전달을 사용하여 백그라운드 서비스 워커에 인증 상태를 요청하세요:

// 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
  // 인증된 API 호출에 토큰 사용
}

main()

전체 가이드: references/content-scripts.md

안정적인 CRX ID

고정 키가 없으면 Chrome이 빌드 시 임의의 키에서 CRX ID를 파생합니다. 이는 빌드할 때마다 변경되어 허용된 출처가 깨집니다.

옵션 A — Plasmo Itero (권장):

  1. Plasmo Itero 키페어 생성 방문
  2. "Generate KeyPairs" 클릭 — Private Key를 안전하게 저장하고 Public Key와 CRX ID 복사

옵션 B — OpenSSL:

openssl genrsa -out key.pem 2048
# Plasmo Itero를 사용하여 올바른 형식으로 공개 키 변환 또는 추출

.env.chrome:

CRX_PUBLIC_KEY="<Itero에서 가져온 PUBLIC KEY>"

package.json:

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

Clerk 대시보드 > 허용된 출처에 chrome-extension://YOUR_STABLE_CRX_ID를 추가하세요.

토큰 캐시 (팝업 닫힘 간 유지)

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}>
저장소 유형범위초기화 시점
chrome.storage.local기기제거 또는 수동 삭제
chrome.storage.session세션브라우저 종료
chrome.storage.sync모든 기기제거 (크기 제한, 8KB)
localStorage팝업만팝업 닫힘 — 인증에 사용하지 마세요

일반적인 문제점

증상원인해결 방법
로그인 시 리디렉션 루프ClerkProvider props에 CRX URL 누락afterSignOutUrl, signInFallbackRedirectUrl 설정
OAuth 버튼이 작동하지 않음팝업에서 OAuth 지원 안 함syncHost를 사용하여 웹 앱에 위임
웹 앱 로그인 후 인증 상태가 오래됨syncHost가 설정되지 않음syncHost prop + host_permissions 추가
웹 로그인 후 사이드패널에 로그아웃 상태 표시알려진 제한 사항사용자가 사이드패널을 닫았다가 다시 열어야 함
60초 후 백그라운드에서 토큰을 가져올 수 없음세션 만료, 백그라운드 새로고침 없음createClerkClient({ background: true }) 사용
콘텐츠 스크립트가 Clerk에 접근할 수 없음격리된 세계 + 출처 제한백그라운드 서비스 워커에 메시지 전달 사용
빌드 후 인증이 깨짐CRX ID가 변경됨.env.chrome을 통해 안정적인 키 설정
PLASMO_PUBLIC_ 변수가 정의되지 않음잘못된 환경 파일.env가 아닌 .env.development 사용
Bot protection 오류Cloudflare가 확장 프로그램에서 지원되지 않음Clerk 대시보드에서 Bot protection 비활성화
토큰 캐시가 지속되지 않음팝업에서 localStorage 사용chrome.storage.local 또는 tokenCache prop 사용

플랜 요구 사항

기능플랜
기본 팝업 인증 (이메일/비밀번호, OTP)무료
패스키무료
syncHostPro 필요 (사용자 정의 도메인)
syncHost를 통한 OAuthPro + 웹 앱에서 OAuth 구성
syncHost를 통한 SAMLEnterprise
Bot protectionN/A — 확장 프로그램에서는 비활성화해야 함

참고

  • clerk-setup — 초기 Clerk 설치
  • clerk-custom-ui — 사용자 정의 흐름 및 외관

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

관련 스킬