feat(chrome-extension): Handle manifest permissions in a more-deterministic fashion

[tmilewski]

Description

Breaking Change: Service Workers / Session Handling

The extension now requires the storage permission in order to maintain sessions and provide authenticated access to other extension features, such as service workers.

How to Update:

• Please add storage to the permissions key in your extension manifest.

Breaking Change: Host Session Syncing

The extension no longer infers the sync host as the original implementation led to increased configuration confusion and false positives.

As such, we've replaced syncSessionWithTab with syncHost. You can set syncHost to the host URL you intend to retrieve the authentication state from.

How to Update:

• Please replace syncSessionWithTab with syncHost="<YOUR_CLERK_FRONTEND_API_DOMAIN>"
• Please ensure that the sync host, along with your app host, is listed in host_permissions and appended with /*. e.g.: https://<YOUR_DOMAIN>/* and https://clerk.<YOUR_DOMAIN>/*

Fixes ECO-212

Feature: Service Workers createClerkClient

We've introduced a new method createClerkClient to handle background tasks in your extension!

import { createClerkClient } from '@clerk/chrome-extension/background';

// Create a new Clerk instance and get a fresh token for the user
async function getToken() {
  const clerk = await createClerkClient({
    publishableKey: process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY,
  });
  return await clerk.session?.getToken();
}

// Create a listener to listen for messages from content scripts
// NOTE: A runtime listener cannot be async.
//       It must return true, in order to keep the connection open and send a response later.
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  // You can use the token in the listener to perform actions on behalf of the user
  // OR send the token back to the content script
  getToken().then(token => sendResponse({ token }));
  return true;
});

Fixes ECO-213

Checklist

• npm test runs as expected.
• npm run build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 9f1f1b9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/clerk-react	Patch
@clerk/chrome-extension	Major
@clerk/clerk-expo	Patch
@clerk/elements	Patch
@clerk/nextjs	Patch
@clerk/remix	Patch
@clerk/tanstack-start	Patch
@clerk/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tmilewski]

!allow-major

[tmilewski]

Reduced complexity of the getClientCookie thus these tests are no longer necessary.

[tmilewski]

Reduced complexity of the validateManifest thus these tests are no longer necessary.

[tmilewski]

Split docs out into separate files as we've found that important details tended to be missed/buried otherwise.

[royanger]

I've been working with this for the last week testing and building apps for documentation and so far there have been no issues. Excited to see this release! 🚀