Docs

Sync auth status between your Chrome Extension and web app

Clerk allows you to sync the authentication state from your web app to your Chrome Extension using Clerk's Sync Host feature. When a user authenticates in your web app, they will also be authenticated in your Chrome Extension.

Warning

Our Chrome Extension SDK currently does not fully support Sync Host on side panels. Currently, if a user authenticates in your web app, they need to close and reopen the side panel to update their auth status.

Warning

This guide assumes assumes that you have followed the Chrome Extension Quickstart and then the Add React Router guide.

Add PLASMO_PUBLIC_CLERK_SYNC_HOST to your environment variables

The PLASMO_PUBLIC_CLERK_SYNC_HOST environment variable defines the host that the Chrome Extension will sync with.

The values for PLASMO_PUBLIC_CLERK_SYNC_HOST will differ between development and production environments. Using separate .env.development and .env.production files allows you to seamlessly pass the appropriate values to your builds.

Use the following tabs to view the instructions for development versus production instances.

Add PLASMO_PUBLIC_CLERK_SYNC_HOST to your .env.development file. The value should be http://localhost.

.env.development
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_FRONTEND_API=https://YOUR_FRONTEND_API_URL
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost

Add PLASMO_PUBLIC_CLERK_SYNC_HOST to your .env.production file. The value should be the domain your web app's production server runs on. For example, https://clerk.com.

.env.production
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_123
CLERK_FRONTEND_API=https://yourdomain.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://yourdomain.com

Add syncHost prop to your <ClerkProvider>

Add the syncHost prop to your Chrome Extension's <ClerkProvider> component. This prop tells the <ClerkProvider> which host to sync with.

src/popup/layouts/root-layout.tsx
import { ClerkProvider, SignedIn, SignedOut, UserButton } from '@clerk/chrome-extension'
import { Link, Outlet, useNavigate } from 'react-router-dom'

const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const SYNC_HOST = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST

if (!PUBLISHABLE_KEY || !SYNC_HOST) {
  throw new Error(
    'Please add the PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY and PLASMO_PUBLIC_CLERK_SYNC_HOST to the .env.development file',
  )
}

export const RootLayout = () => {
  const navigate = useNavigate()

  return (
    <ClerkProvider
      routerPush={(to) => navigate(to)}
      routerReplace={(to) => navigate(to, { replace: true })}
      publishableKey={PUBLISHABLE_KEY}
      afterSignOutUrl="/"
      syncHost={SYNC_HOST}
    >
      <div className="plasmo-w-[785px] plasmo-h-[600px]">
        <main>
          <Outlet />
        </main>
        <footer>
          <SignedIn>
            <Link to="/settings">Settings</Link>
            <UserButton />
          </SignedIn>
          <SignedOut>
            <Link to="/">Home</Link>
            <Link to="/sign-in">Sign In</Link>
            <Link to="/sign-up">Sign Up</Link>
          </SignedOut>
        </footer>
      </div>
    </ClerkProvider>
  )
}

Hide unsupported authentication methods

When using the Sync Host feature, authentication methods that you want to use in your web app may not be fully supported in the Chrome Extension environment. To hide unsupported methods in your Chrome Extension, you can use the appearance prop with your extension's <SignUp> and <SignIn> components as demonstrated in the following examples.

src/popup/pages/sign-up.tsx
<SignUp
  appearance={{
    elements: {
      socialButtonsRoot: 'plasmo-hidden',
      dividerRow: 'plasmo-hidden',
    },
  }}
/>
src/popup/pages/sign-in.tsx
<SignIn
  appearance={{
    elements: {
      socialButtonsRoot: 'plasmo-hidden',
      dividerRow: 'plasmo-hidden',
    },
  }}
/>

Configure host_permissions

host_permissions specifies which hosts, or websites, will have permission to sync auth state with your app. It accepts an array, allowing you to add more than one host.

In the package.json file, in the manifest object, update the host_permissions array. Remove http://localhost/* and replace with $PLASMO_PUBLIC_CLERK_SYNC_HOST/*, as shown in the following example:

package.json
{
  // The rest of your package.json file
  "manifest": {
    "key": "$CRX_PUBLIC_KEY",
    "permissions": ["cookies", "storage"],
    "host_permissions": ["$PLASMO_PUBLIC_CLERK_SYNC_HOST/*", "$CLERK_FRONTEND_API/*"]
  }
}

Add the Extension's ID to your web app's allowed_origins

To allow your Chrome Extension to sync with your web app, you must add the extension's ID to your web app's allowed_origins.

Note

If you have not configured a consistent key, you will have to repeat this step every time your extension's ID changes.

  1. In the Clerk Dashboard, navigate to the API keys page.
  2. Copy your Secret Key. It should start with sk_test_ or sk_live_ for your development and production instances, respectively.
  3. In your terminal, paste the following command. Replace YOUR_SECRET_KEY with your Clerk Secret Key and the <CHROME_EXTENSION_KEY> with your extension's ID.

The final result should resemble the following:

terminal
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://<CHROME_EXTENSION_ID>"]}'

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on