Clerk Chrome Extension Patterns

What it does

When your agent uses it

• : Chrome extension auth
• Background service worker token
• CreateClerkClient
• Headless extension

Example prompts

• “/clerk-chrome-extension-patterns”

Requirements

• Node.js
• A credential in PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
• A credential in PUBLISHABLE_KEY
• Compatibility (from SKILL.md): Requires PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY (Plasmo prefix for public env vars) and CLERK_FRONTEND_API.
• Pre-approved tools (allowed-tools): WebFetch

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

1. 1OAuth (Google, GitHub, etc.) and SAML are NOT supported in popups or side panels -- use syncHost to delegate auth to your web app
2. 2Email links (magic links) don't work in popups -- the popup closes when the user clicks outside, resetting sign-in state
3. 3Side panels don't auto-refresh auth state -- users must close and reopen the side panel after signing in via the web app
4. 4Service workers and content scripts have NO access to Clerk React hooks -- use createClerkClient() or message passing
5. 5Extension URLs use chrome-extension:// not http:// -- all redirect URLs must use chrome.runtime.getURL('.')
6. 6Without a stable CRX ID, every rebuild breaks auth -- configure key in manifest BEFORE deploying
7. 7Content scripts cannot use Clerk directly due to origin restrictions -- Clerk enforces strict allowed origins
8. 8Bot protection must be DISABLED in Clerk Dashboard -- Cloudflare bot detection is not supported in extension environments

What it can do on your machine

Read from SKILL.md and the folder at commit e5554c5. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • WebFetch

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • npx
  • npm
  • curl
  • openssl

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • api.clerk.com

  Also links to:

  • itero.plasmo.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
  • PUBLISHABLE_KEY
  • CRX_PUBLIC_KEY
  • GET_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY (Plasmo prefix for public env vars) and CLERK_FRONTEND_API.

  From compatibility in the SKILL.md frontmatter.

Context cost

Clerk Chrome Extension Patterns loads about 2.9k tokens when it runs, and up to ~6.7k if it reads all its reference files. Until then it costs about 93 tokens; SKILL.md has 749 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~93

When it runs · the whole SKILL.md, loaded when a task matches

~2.9k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:59

  `.env.development`:

• NoteMentions a .env fileSKILL.md:108

  `.env.development`:

• NoteMentions a .env fileSKILL.md:115

  `.env.production`:

• NoteMentions a .env fileSKILL.md:298

  **`.env.chrome`:**

• NoteMentions a .env fileSKILL.md:355

  X ID rotated | Configure stable key via `.env.chrome` |

• NoteMentions a .env fileSKILL.md:356

  _` var undefined | Wrong env file | Use `.env.development`, not `.env` |

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from geekskai/blog at commit e5554c5, republished under its MIT licence (© geekskai). 749 words, ~2,915 tokens.

name

clerk-chrome-extension-patterns

description

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

allowed-tools

WebFetch

compatibility

Requires PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY (Plasmo prefix for public env vars) and CLERK_FRONTEND_API.

license

MIT

metadata.author

clerk

metadata.version

2.0.0

metadata.references

references/sync-host.md, references/create-clerk-client.md, references/content-scripts.md, references/headless-extension.md

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

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev

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

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost

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

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

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

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

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

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

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

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
}

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

openssl genrsa -out key.pem 2048
# Use Plasmo Itero to convert or extract the public key in correct format

CRX_PUBLIC_KEY="<PUBLIC KEY from Itero>"

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

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

© geekskai, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 8 other files (references) in .agents/skills/clerk-chrome-extension-patterns of geekskai/blog.

• SKILL.md
• evals/evals.json
• references/content-scripts.md
• references/create-clerk-client.md
• references/headless-extension.md
• references/sync-host.md
• templates/chrome-ext-basic-auth/package.json
• templates/chrome-ext-basic-auth/src/popup.tsx
• templates/chrome-ext-basic-auth/tsconfig.json

Open the folder on GitHubat commit e5554c5