feat: Introduce Electron SDK

.changeset/electron-package-scaffold.md

@@ -0,0 +1,2 @@
+---
+---

packages/electron/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clerk, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/electron/README.md

@@ -0,0 +1,104 @@
+<p align="center">
+  <a href="https://clerk.com?utm_source=github&utm_medium=clerk_electron" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://images.clerk.com/static/logo-dark-mode-400x400.png">
+      <img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64">
+    </picture>
+  </a>
+  <br />
+  <h1 align="center">@clerk/electron</h1>
+</p>
+
+<div align="center">
+
+[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_electron)
+[![Follow on X](https://img.shields.io/twitter/follow/clerk?style=social)](https://x.com/intent/follow?screen_name=clerk)
+
+[Changelog](https://github.com/clerk/javascript/blob/main/packages/electron/CHANGELOG.md)
+·
+[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml)
+·
+[Request a Feature](https://feedback.clerk.com/roadmap)
+·
+[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_electron)
+
+</div>
+
+## Getting Started
+
+[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_electron) is the easiest way to add authentication and user management to your Electron application.
+
+> [!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 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 { app, BrowserWindow, net, protocol } from 'electron';
+import { setupMain } from '@clerk/electron';
+import { storage } from '@clerk/electron/storage';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+setupMain({
+  storage: storage(),
+  renderer: {
+    scheme: 'my-app',
+    host: 'renderer',
+  },
+});
+
+app.whenReady().then(() => {
+  protocol.handle('my-app', request => {
+    const url = new URL(request.url);
+    const file = url.pathname === '/' ? 'index.html' : url.pathname;
+
+    return net.fetch(pathToFileURL(join(__dirname, '../renderer', file)).toString());
+  });
+
+  const win = new BrowserWindow({
+    webPreferences: {
+      preload: join(__dirname, '../preload/index.js'),
+    },
+  });
+
+  win.loadURL('my-app://renderer/');
+});
+```
+
+In `my-app://renderer/sign-in`, `my-app` is the scheme, `renderer` is the host, `my-app://renderer` is the origin, and `/sign-in` is the path. If your renderer uses path-based routing, serve every route from the same origin and fall back to your renderer entrypoint as needed.
+
+```tsx
+// renderer.tsx
+import { ClerkProvider } from '@clerk/electron/react';
+
+<ClerkProvider publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}>{/* ... */}</ClerkProvider>;
+```
+
+## Support
+
+For help, visit our [support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_electron).
+
+## Contributing
+
+We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## Security
+
+`@clerk/electron` follows good practices of security, but 100% security cannot be assured.
+
+`@clerk/electron` 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](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._
+
+## License
+
+This project is licensed under the **MIT license**.
+
+See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/electron/LICENSE) for more information.

packages/electron/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@clerk/electron",
+  "version": "0.0.0",
+  "description": "Clerk SDK for Electron",
+  "keywords": [
+    "clerk",
+    "electron",
+    "auth",
+    "authentication",
+    "session",
+    "jwt",
+    "desktop"
+  ],
+  "homepage": "https://clerk.com/",
+  "bugs": {
+    "url": "https://github.com/clerk/javascript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clerk/javascript.git",
+    "directory": "packages/electron"
+  },
+  "license": "MIT",
+  "author": "Clerk",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./preload": {
+      "import": {
+        "types": "./dist/types/preload/index.d.ts",
+        "default": "./dist/esm/preload/index.js"
+      },
+      "require": {
+        "types": "./dist/types/preload/index.d.ts",
+        "default": "./dist/cjs/preload/index.js"
+      }
+    },
+    "./storage": {
+      "import": {
+        "types": "./dist/types/storage/index.d.ts",
+        "default": "./dist/esm/storage/index.js"
+      },
+      "require": {
+        "types": "./dist/types/storage/index.d.ts",
+        "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",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "preload"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:declarations": "tsc -p tsconfig.declarations.json",
+    "clean": "rimraf ./dist",
+    "dev": "tsup --watch",
+    "format": "node ../../scripts/format-package.mjs",
+    "format:check": "node ../../scripts/format-package.mjs --check",
+    "lint": "eslint src",
+    "lint:attw": "attw --pack . --profile node16 --ignore-rules unexpected-module-syntax",
+    "lint:publint": "publint",
+    "test": "vitest run",
+    "test:ci": "vitest run --maxWorkers=70%",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@clerk/clerk-js": "workspace:^",
+    "@clerk/react": "workspace:^",
+    "@clerk/ui": "workspace:^",
+    "tslib": "catalog:repo"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "electron": "^39.2.6",
+    "electron-store": "^8.2.0"
+  },
+  "peerDependencies": {
+    "electron": ">=28",
+    "electron-store": "^8.2.0",
+    "react": "catalog:peer-react",
+    "react-dom": "catalog:peer-react"
+  },
+  "peerDependenciesMeta": {
+    "electron-store": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/electron/src/global.d.ts

@@ -0,0 +1,13 @@
+import type { TokenCache } from './shared/types';
+
+declare const PACKAGE_NAME: string;
+declare const PACKAGE_VERSION: string;
+declare const __DEV__: boolean;
+
+declare global {
+  interface Window {
+    __clerk_internal_electron?: {
+      tokenCache: TokenCache;
+    };
+  }
+}

packages/electron/src/index.ts

@@ -0,0 +1 @@
+export { setupMain } from './main/setup-main';

packages/electron/src/main/__tests__/ipc-handlers.test.ts

@@ -0,0 +1,63 @@
+import { ipcMain } from 'electron';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import type { TokenStorage } from '../../shared/types';
+import { setupTokenCacheIpcHandlers } from '../ipc-handlers';
+
+const ipcEvent = {} as Electron.IpcMainInvokeEvent;
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: vi.fn(),
+    removeHandler: vi.fn(),
+  },
+}));
+
+describe('setupTokenCacheIpcHandlers', () => {
+  const storage: TokenStorage = {
+    getItem: vi.fn(),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('registers token cache IPC handlers', () => {
+    setupTokenCacheIpcHandlers(storage);
+
+    expect(ipcMain.handle).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.getToken, expect.any(Function));
+    expect(ipcMain.handle).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, expect.any(Function));
+    expect(ipcMain.handle).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, expect.any(Function));
+  });
+
+  it('delegates token operations to the storage adapter', async () => {
+    vi.mocked(storage.getItem).mockResolvedValue('jwt');
+
+    setupTokenCacheIpcHandlers(storage);
+
+    const getTokenHandler = vi.mocked(ipcMain.handle).mock.calls[0][1];
+    const saveTokenHandler = vi.mocked(ipcMain.handle).mock.calls[1][1];
+    const clearTokenHandler = vi.mocked(ipcMain.handle).mock.calls[2][1];
+
+    await expect(getTokenHandler(ipcEvent, 'token-key')).resolves.toBe('jwt');
+    await saveTokenHandler(ipcEvent, 'token-key', 'jwt');
+    await clearTokenHandler(ipcEvent, 'token-key');
+
+    expect(storage.getItem).toHaveBeenCalledWith('token-key');
+    expect(storage.setItem).toHaveBeenCalledWith('token-key', 'jwt');
+    expect(storage.removeItem).toHaveBeenCalledWith('token-key');
+  });
+
+  it('removes registered handlers on cleanup', () => {
+    const cleanup = setupTokenCacheIpcHandlers(storage);
+
+    cleanup();
+
+    expect(ipcMain.removeHandler).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.getToken);
+    expect(ipcMain.removeHandler).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken);
+    expect(ipcMain.removeHandler).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken);
+  });
+});