@odla-ai/auth-clerk

⚠️ Early access — pre-1.0. Agents work from bounded runbooks; humans approve credentials, production changes, releases, and merges. APIs and exact package availability can change. Review the documented guarantees and limitations; this software is MIT-licensed and provided without warranty.

Clerk end-user auth as a themed, config-driven odla capability — not a bag of components you re-wire per app.

It wraps vanilla @clerk/clerk-js (no @clerk/clerk-react). Its provider, hooks, gates, and imperative widget mounts are authored and shipped against Preact.

Ask the runbooks first. odla's operational procedures live in a database, not in this file: npx @odla-ai/cli runbook ask "<question>" returns the current steps, and unlike anything written here it cannot be out of date. Use it before searching the web or working from memory. This README and the JSDoc in the shipped .d.ts are the version-matched API reference; a runbook is the procedure. Most tasks need an answer from both.

What's in the box

• <ClerkGate> — provider (replaces <ClerkProvider>). Loads Clerk once, provides it via context.
• useClerkAuth() — { isLoaded, isSignedIn, user, session, getToken, signOut }, reactive via the Clerk client's external-store subscription.
• <SignedIn> / <SignedOut> — conditional render (blank until loaded, so no signed-out flash).
• <SignIn> / <UserButton> — mount Clerk's widgets imperatively; write them like components.
• clerkAppearanceFromTokens() — maps odla-ui --ui-* design tokens into a Clerk appearance, including accent/on-accent, both surfaces, text/input, border/ring, status colors, radius, font, and card shadow. It supplies both current and legacy Clerk variable aliases so every widget matches the theme.
• clerkIntegration — the integration descriptor (settings, secrets, data-sync contract, provisioning steps) as data.

Usage

import { ClerkGate, SignedIn, SignedOut, useClerkAuth, SignIn, clerkAppearanceFromTokens } from "@odla-ai/auth-clerk";

// The host app loads @odla-ai/ui tokens (for theming) and supplies the
// publishable key (e.g. fetched from /registry/config).
<ClerkGate publishableKey={key} afterSignOutUrl="/" appearance={clerkAppearanceFromTokens()}>
  <SignedOut><SignIn routing="hash" /></SignedOut>
  <SignedIn>{/* app */}</SignedIn>
</ClerkGate>

Install Preact alongside the package. No React aliases are required:

npm install @odla-ai/auth-clerk preact

The capability, not just the UI

Turning Clerk "on" for an app is a registry setting (auth[env].publishableKey), not a code flag — this package renders against that config. What settings and secrets it needs, what the CLI provisions, and what data syncs to Clerk ($users: id, email, userType, allowedIds) all live in clerkIntegration.

Browser SDK and declaration dependencies

Clerk 5 still loads from its own frontend API CDN. The npm browser SDK is not installed or bundled by this package. Declarations use Clerk's public @clerk/shared/types interface, which is also the interface implemented by clerk-js, rather than importing the implementation class and its unused wallet-adapter dependency tree. TypeScript consumers need no optional SDK peer.

ClerkClient.instance exposes that public interface, not implementation-only class members. A host can still supply its own compatible window.Clerk; this package does not redeclare that global. The CDN script and public sign-in, session, sign-out, and widget behavior remain unchanged.

A clean npm audit covers the installed graph, not the remotely loaded CDN script. Keep evaluating the browser provider separately; removing an unused local SDK is not a claim about the security of every Clerk feature.

MIT licensed. Early access — use at your own risk.