feat(electron): Add initial React integration export (#8806)

Author: wobsoriano

packages/electron/README.md

@@ -31,10 +31,29 @@
 > [!WARNING]
 > `@clerk/electron` is under active development and is not yet ready for production use. The API is incomplete and subject to change.
 
-This package exposes two entrypoints, targeting Electron's distinct runtime contexts:
+This package exposes entrypoints for Electron's distinct runtime contexts:
 
 - `@clerk/electron` — for use in the Electron **main** process.
 - `@clerk/electron/preload` — for use in Electron **preload** scripts.
+- `@clerk/electron/react` — for use in the Electron **renderer** process.
+- `@clerk/electron/storage` — default token storage backed by `electron-store`.
+
+```ts
+// main.ts
+import { setupMain } from '@clerk/electron';
+import { storage } from '@clerk/electron/storage';
+
+setupMain({
+  storage: storage(),
+});
+```
+
+```tsx
+// renderer.tsx
+import { ClerkProvider } from '@clerk/electron/react';
+
+<ClerkProvider publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}>{/* ... */}</ClerkProvider>;
+```
 
 ## Support
 

packages/electron/package.json

@@ -54,6 +54,16 @@
         "default": "./dist/cjs/storage/index.js"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/types/react/index.d.ts",
+        "default": "./dist/esm/react/index.js"
+      },
+      "require": {
+        "types": "./dist/types/react/index.d.ts",
+        "default": "./dist/cjs/react/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/cjs/index.js",
@@ -78,6 +88,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@clerk/clerk-js": "workspace:^",
+    "@clerk/react": "workspace:^",
+    "@clerk/ui": "workspace:^",
     "tslib": "catalog:repo"
   },
   "devDependencies": {
@@ -87,11 +100,16 @@
   },
   "peerDependencies": {
     "electron": ">=28",
-    "electron-store": "^8.2.0"
+    "electron-store": "^8.2.0",
+    "react": "catalog:peer-react",
+    "react-dom": "catalog:peer-react"
   },
   "peerDependenciesMeta": {
     "electron-store": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "engines": {

packages/electron/src/react/__tests__/ClerkProvider.test.tsx

@@ -0,0 +1,111 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkProvider } from '../index';
+
+let capturedProviderProps: Record<string, unknown> | null = null;
+let beforeRequest:
+  | ((request: { credentials?: RequestCredentials; headers?: Headers; url?: URL }) => Promise<void>)
+  | null = null;
+let afterResponse: ((request: unknown, response: Response) => Promise<void>) | null = null;
+
+const clerkConstructor = vi.hoisted(() => vi.fn());
+
+vi.mock('@clerk/clerk-js', () => ({
+  Clerk: class MockClerk {
+    constructor(publishableKey: string) {
+      clerkConstructor(publishableKey);
+    }
+
+    __internal_onBeforeRequest(cb: typeof beforeRequest) {
+      beforeRequest = cb;
+    }
+
+    __internal_onAfterResponse(cb: typeof afterResponse) {
+      afterResponse = cb;
+    }
+  },
+}));
+
+vi.mock('@clerk/react/internal', () => ({
+  InternalClerkProvider: (props: Record<string, unknown>) => {
+    capturedProviderProps = props;
+    return <div>{props.children as React.ReactNode}</div>;
+  },
+}));
+
+vi.mock('@clerk/ui', () => ({
+  ui: { ClerkUI: 'mock-ui' },
+}));
+
+describe('Electron ClerkProvider', () => {
+  const tokenCache = {
+    clearToken: vi.fn(),
+    getToken: vi.fn(),
+    saveToken: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    capturedProviderProps = null;
+    beforeRequest = null;
+    afterResponse = null;
+    vi.stubGlobal('window', {
+      __clerk_internal_electron: {
+        tokenCache,
+      },
+    });
+  });
+
+  it('renders React ClerkProvider with Electron defaults', () => {
+    renderToStaticMarkup(
+      <ClerkProvider
+        publishableKey='pk_test_provider'
+        signInUrl='/sign-in'
+      >
+        <span>App</span>
+      </ClerkProvider>,
+    );
+
+    expect(clerkConstructor).toHaveBeenCalledWith('pk_test_provider');
+    expect(capturedProviderProps).toMatchObject({
+      publishableKey: 'pk_test_provider',
+      signInUrl: '/sign-in',
+      standardBrowser: false,
+      ui: { ClerkUI: 'mock-ui' },
+    });
+    expect(capturedProviderProps?.Clerk).toBeDefined();
+    expect(capturedProviderProps?.__internal_nativeOAuthHandler).toBeUndefined();
+  });
+
+  it('adds native request params and Authorization from the Electron token cache', async () => {
+    tokenCache.getToken.mockResolvedValue('client-jwt');
+    renderToStaticMarkup(<ClerkProvider publishableKey='pk_test_before_request'>App</ClerkProvider>);
+
+    const request = {
+      headers: new Headers(),
+      url: new URL('https://api.clerk.test/v1/client'),
+    };
+    await beforeRequest?.(request);
+
+    expect(request.credentials).toBe('omit');
+    expect(request.url.searchParams.get('_is_native')).toBe('1');
+    expect(request.headers.get('Authorization')).toBe('Bearer client-jwt');
+    expect(tokenCache.getToken).toHaveBeenCalledWith('__clerk_client_jwt');
+  });
+
+  it('stores Authorization response headers in the Electron token cache', async () => {
+    renderToStaticMarkup(<ClerkProvider publishableKey='pk_test_after_response'>App</ClerkProvider>);
+
+    await afterResponse?.(
+      {},
+      new Response(null, {
+        headers: {
+          Authorization: 'Bearer updated-client-jwt',
+        },
+      }),
+    );
+
+    expect(tokenCache.saveToken).toHaveBeenCalledWith('__clerk_client_jwt', 'updated-client-jwt');
+  });
+});

packages/electron/src/react/create-clerk-instance.ts

@@ -0,0 +1,40 @@
+import { Clerk } from '@clerk/clerk-js';
+
+const CLERK_CLIENT_JWT_KEY = '__clerk_client_jwt';
+
+type ClerkInstance = InstanceType<typeof Clerk>;
+
+let cached: { instance: ClerkInstance; publishableKey: string } | null = null;
+
+export function createClerkInstance(publishableKey: string): ClerkInstance {
+  if (cached?.publishableKey === publishableKey) {
+    return cached.instance;
+  }
+
+  const clerk = new Clerk(publishableKey);
+
+  clerk.__internal_onBeforeRequest(async request => {
+    request.credentials = 'omit';
+    request.url?.searchParams.append('_is_native', '1');
+
+    const token = await window.__clerk_internal_electron?.tokenCache.getToken(CLERK_CLIENT_JWT_KEY);
+    if (token) {
+      const headers = new Headers(request.headers);
+      headers.set('Authorization', `Bearer ${token}`);
+      request.headers = headers;
+    }
+  });
+
+  clerk.__internal_onAfterResponse(async (_request, response) => {
+    const authorization = (response as Response).headers.get('Authorization');
+    if (!authorization) {
+      return;
+    }
+
+    const token = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : authorization;
+    await window.__clerk_internal_electron?.tokenCache.saveToken(CLERK_CLIENT_JWT_KEY, token);
+  });
+
+  cached = { instance: clerk, publishableKey };
+  return clerk;
+}

packages/electron/src/react/index.tsx

@@ -0,0 +1,35 @@
+import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
+import { InternalClerkProvider as ReactClerkProvider } from '@clerk/react/internal';
+import { ui } from '@clerk/ui';
+import type { ReactNode } from 'react';
+
+import { createClerkInstance } from './create-clerk-instance';
+
+export type ClerkProviderProps = Omit<
+  ReactClerkProviderProps,
+  'Clerk' | 'children' | 'publishableKey' | 'standardBrowser' | 'ui'
+> & {
+  children: ReactNode;
+  /**
+   * Your Clerk publishable key, available in the Clerk Dashboard.
+   */
+  publishableKey: string;
+};
+
+export function ClerkProvider({ children, publishableKey, ...props }: ClerkProviderProps): JSX.Element {
+  const clerk = createClerkInstance(publishableKey);
+
+  return (
+    <ReactClerkProvider
+      {...props}
+      Clerk={clerk}
+      publishableKey={publishableKey}
+      standardBrowser={false}
+      ui={ui}
+    >
+      {children}
+    </ReactClerkProvider>
+  );
+}
+
+export * from '@clerk/react';

packages/electron/tsconfig.json

@@ -19,5 +19,6 @@
     "declarationMap": true,
     "emitDeclarationOnly": true
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/__tests__/**"]
 }

packages/electron/tsup.config.ts

@@ -9,7 +9,7 @@ export default defineConfig(overrideOptions => {
   const shouldPublish = !!overrideOptions.env?.publish;
 
   const common: Options = {
-    entry: ['./src/index.ts', './src/preload/index.ts', './src/storage/index.ts'],
+    entry: ['./src/index.ts', './src/preload/index.ts', './src/react/index.tsx', './src/storage/index.ts'],
     bundle: true,
     clean: true,
     minify: false,