Communitygithub.com

deangilmoreremix/videoremix.vip2

Chrome拡張機能の認証を @clerk/chrome-extension で実装します。ポップアップ/サイドパネルのセットアップ、OAuth/SAMLのための syncHost、サービスワーカーやヘッドレス拡張機能向けの createClerkClient、安定したCRX IDを提供します。

videoremix.vip2 とは?

このスキルは、Chrome拡張機能(Plasmoフレームワーク対応)にClerk認証を統合するための包括的なガイドです。ポップアップやサイドパネル内での直接的なOAuth/SAML非対応といった拡張機能環境の制約に対処し、セキュアな認証フローを実現します。主な機能として、ポップアップ/サイドパネル向けの基本的な認証、Webアプリと連携するsyncHost(OAuth/SAML対応)、バックグラウンドサービスワーカーやヘッドレス拡張機能向けのcreateClerkClient、コンテンツスクリプトとのメッセージパッシング、安定したCRX IDの設定、トークンキャッシュの永続化などをカバー。Claude Code、Cursor、CodexなどのAIエージェントが拡張機能開発時に参照するための実用的なコードスニペット、設定手順、トラブルシューティング表を提供します。

対応~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を使用してWebアプリに認証を委任してください
  2. メールリンク(マジックリンク)はポップアップで機能しません — ユーザーがポップアップ外をクリックするとポップアップが閉じ、サインイン状態がリセットされます
  3. サイドパネルは認証状態を自動的に更新しません — ユーザーはWebアプリでサインインした後、サイドパネルを閉じて再度開く必要があります
  4. サービスワーカーとコンテンツスクリプトはClerk Reactフックにアクセスできません — createClerkClient()またはメッセージパッシングを使用してください
  5. 拡張機能のURLはchrome-extension://を使用し、http://は使用しません — すべてのリダイレクトURLはchrome.runtime.getURL('.')を使用する必要があります
  6. 安定したCRX IDがない場合、ビルドのたびに認証が壊れます — デプロイ前にマニフェストでkeyを設定してください
  7. オリジン制限により、コンテンツスクリプトはClerkを直接使用できません — Clerkは許可されたオリジンを厳格にチェックします
  8. Clerkダッシュボードでボット保護を無効にする必要があります — Cloudflareボット検出は拡張機能環境ではサポートされていません

認証オプション

方法ポップアップサイドパネルsyncHost(Webアプリ連携)
メール + 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ダッシュボードでネイティブ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 — Webアプリと認証を同期

OAuth、SAMLが必要な場合、または拡張機能がWebアプリからのサインイン状態を反映させたい場合に使用します。

仕組み: 拡張機能はhost_permissionsを介してWebアプリのドメインからClerkセッションCookieを読み取ります。

ステップ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プロパティを追加:

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をWebアプリの許可されたオリジンに追加:

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

Vanilla JS / サービスワーカー向け createClerkClient()

@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

ヘッドレス拡張機能(ポップアップ、サイドパネルなし)

完全にバックグラウンドで実行され、Webアプリと同期する拡張機能向け。

syncHost + createClerkClientをbackground: trueで使用し、WebアプリのCookieから認証状態を読み取ります。

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で同期ホストドメインのhost_permissionsが必要です。

完全なガイド: references/headless-extension.md

コンテンツスクリプト

コンテンツスクリプトは、Webページに注入された分離された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 Generate Keypairsにアクセス
  2. 「Generate KeyPairs」をクリック — 秘密鍵を安全に保存し、公開鍵とCRX IDをコピーします

オプションB — OpenSSL:

openssl genrsa -out key.pem 2048
# Plasmo Iteroを使用して公開鍵を正しい形式に変換または抽出します

.env.chrome:

CRX_PUBLIC_KEY="<Iteroから取得した公開鍵>"

package.json:

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

chrome-extension://YOUR_STABLE_CRX_IDをClerkダッシュボード > 許可されたオリジンに追加します。

トークンキャッシュ(ポップアップを閉じても保持)

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プロパティにCRX URLが欠落afterSignOutUrl、signInFallbackRedirectUrlを設定
OAuthボタンが動作しないOAuthはポップアップでサポートされていないsyncHostを使用してWebアプリに委任
Webアプリサインイン後に認証状態が古いsyncHostが設定されていないsyncHostプロパティ + host_permissionsを追加
Webサインイン後、サイドパネルにサインアウトと表示既知の制限ユーザーはサイドパネルを閉じて再度開く必要がある
バックグラウンドが60秒後にトークンを取得できないセッション期限切れ、バックグラウンド更新なしcreateClerkClient({ background: true })を使用
コンテンツスクリプトがClerkにアクセスできない分離された環境 + オリジン制限バックグラウンドサービスワーカーへのメッセージパッシングを使用
ビルド後に認証が壊れるCRX IDが変更された.env.chromeで安定したキーを設定
PLASMO_PUBLIC_変数が未定義間違ったenvファイル.envではなく.env.developmentを使用
ボット保護エラーCloudflareは拡張機能でサポートされていないClerkダッシュボードでボット保護を無効化
トークンキャッシュが保持されないポップアップでlocalStorageを使用chrome.storage.localを使用するか、tokenCacheプロパティを渡す

プラン要件

機能プラン
基本的なポップアップ認証(メール/パスワード、OTP)無料
パスキー無料
syncHostPro(カスタムドメイン)が必要
syncHost経由のOAuthPro + WebアプリでOAuth設定済み
syncHost経由のSAMLEnterprise
ボット保護なし — 拡張機能では無効にする必要があります

関連項目

  • 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

関連スキル