āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/sessions/sync-host ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
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.
<Steps> ## Add `PLASMO_PUBLIC_CLERK_SYNC_HOST` to your environment variables[!WARNING] This guide assumes assumes that you have followed the Chrome Extension Quickstart and then the Add React Router guide.
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.
<Tabs items={["Development", "Production"]}>
<Tab>
Add PLASMO_PUBLIC_CLERK_SYNC_HOST to your .env.development file. The value should be http://localhost.
```env {{ filename: '.env.development', mark: [3] }}
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
CLERK_FRONTEND_API=https://{{fapi_url}}
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost
```
</Tab>
<Tab>
Add `PLASMO_PUBLIC_CLERK_SYNC_HOST` to your `.env.production` file. The value should be the [domain that your Clerk Frontend API](https://dashboard.clerk.com/~/domains) runs on. For example, `https://clerk.your-domain.com`.
```env {{ filename: '.env.production', mark: [3] }}
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_123
CLERK_FRONTEND_API=https://clerk.your-domain.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.your-domain.com
```
</Tab>
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.
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>
)
}
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.
<CodeBlockTabs options={["<SignUp>", "<SignIn>"]}>
tsx {{ filename: 'src/popup/pages/sign-up.tsx', mark: [[3, 7]] }} <SignUp appearance={{ elements: { socialButtonsRoot: 'plasmo-hidden', dividerRow: 'plasmo-hidden', }, }} />
```tsx {{ filename: 'src/popup/pages/sign-in.tsx', mark: [[3, 7]] }}
<SignIn
appearance={{
elements: {
socialButtonsRoot: 'plasmo-hidden',
dividerRow: 'plasmo-hidden',
},
}}
/>
```
host_permissionshost_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:
{
// 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/*"]
}
}
allowed_originsTo 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.
sk_test_ or sk_live_ for your development and production instances, respectively.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:
curl -X PATCH https://api.clerk.com/v1/instance \
-H "Authorization: Bearer {{secret}}" \
-H "Content-type: application/json" \
-d '{"allowed_origins": ["chrome-extension://<CHROME_EXTENSION_ID>"]}'
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā