@clerk/chrome-extension

Getting Started

Clerk is the easiest way to add authentication and user management to your Browser Extension. Add sign up, sign in, and profile management to your application in minutes.

Prerequisites

• Node.js >=20.9.0 or later
• An existing Clerk application. Create your account for free.
• An existing React app (using Vite for example)

Feature Support

Please see the latest extension authentication support matrix in the Clerk documentation for more information.

Usage

1. Installation: npm install @clerk/chrome-extension

2. Set a consistent extension key: A browser extension can be identified by its unique key, in a similar way to how a website can be identified by its domain. You will need to explicitly configure your extension's key or it will change often. If the key changes, it can cause the extension to fail. See the Configure a Consistent Key guide for more information.

3. Update Clerk Settings: Once you've set up a consistent extension key, you'll need to configure your Clerk settings to allow the extension to communicate with your Clerk API. You can do this by adding the extension key to the list of allowed origins in your Clerk settings. Setting the allowed_origins is required for both Development and Production instances.

   curl  -X PATCH https://api.clerk.com/v1/instance \
         -H "Content-type: application/json" \
         -H "Authorization: Bearer <CLERK_SECRET_KEY>" \
         -d '{"allowed_origins": ["chrome-extension://<YOUR_EXTENSION_KEY>"]}'
   

4. Set Environment Variables: Retrieve the Publishable key from your Clerk dashboard and set it as an environment variable.

   # Vite
   VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx
   

   # Plasmo
   PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
   

5. Update the extension manifest: You'll need to update your extension manifest permissions to support Clerk.

   1. Base configuration: Use this if you plan to only use Clerk in the context of the extension.
   2. Session sync configuration: Use this if you plan to share authentication with a website in the same browser.

6. Add Clerk to your app: Though not required, we generally suggest using Plasmo for browser extension development. This will enforce common standards across your extension as well as allow for easier integration with other browsers in the future.

   1. Via ClerkProvider: This is the general approach to all extensions. From here you'll be able to support extension-only authentication as well as sharing authentication with a website in the same browser.
   2. Via service workers: If you also require the use of background service workers, this will allow you to access the Clerk client from the extension context.

Example repositories

• Quickstart: The extension is using its own authentication
• SyncHost, Service Workers and react-router: The extension shares auth with a website in the same browser, needs to access user information from Clerk in a service worker or needs to use react-router

Support

For help, visit our support page.

Community

Join our Discord community to connect with other developers.

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.

Security

@clerk/chrome-extension follows good practices of security, but 100% security cannot be assured.

@clerk/chrome-extension is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.