WorkOS AuthKit for Vanilla JavaScript
Decision Tree
Step 1: Fetch README (BLOCKING)
WebFetch: https://github.com/workos/authkit-js/blob/main/README.md
README is source of truth. If this skill conflicts, follow README.
Step 2: Detect Project Type
Has package.json with build tool (Vite, webpack, Parcel)? YES -> Bundled project (npm install) NO -> CDN/Static project (script tag)
Step 3: Follow README Installation
-
Bundled: Use package manager install from README
-
CDN: Use unpkg script tag from README
Step 4: Implement Per README
Follow README examples for:
-
Client initialization
-
Sign in/out handlers
-
User state management
Critical API Quirk
createClient() is async - returns a Promise, not a client directly.
// CORRECT const authkit = await createClient(clientId);
Verification Checklist
-
README fetched and read before writing code
-
Project type detected (bundled vs CDN)
-
SDK installed/script added
-
createClient() called with await
-
Client ID provided (env var or hardcoded)
-
Sign in called from user gesture (click handler)
-
No console errors on page load
-
Auth UI updates on sign in/out
Environment Variables
Bundled projects only:
-
Vite: VITE_WORKOS_CLIENT_ID
-
Webpack: REACT_APP_WORKOS_CLIENT_ID or custom
-
No WORKOS_API_KEY needed (client-side SDK)
Error Recovery
Error Cause Fix
WorkOS is not defined
CDN not loaded Add script to <head> before your code
createClient is not a function
Wrong import npm: check import path; CDN: use WorkOS.createClient
clientId is required
Undefined env var Check env prefix matches build tool
CORS errors file:// protocol Use local dev server (npx serve )
Popup blocked Not user gesture Call signIn() only from click handler
Auth state lost Token not persisted Check localStorage in dev tools
Task Flow
-
preflight: Fetch README, detect project type, verify env vars
-
install: Add SDK per project type
-
callback: SDK handles internally (no server route needed)
-
provider: Initialize client with await createClient()
-
ui: Add auth buttons and state display
-
verify: Build (if bundled), check console