WorkOS AuthKit for Vanilla JavaScript
Decision Tree
Step 1: Fetch README (BLOCKING)
WebFetch: https://raw.githubusercontent.com/workos/authkit-js/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 (ALL MUST PASS)
Run these commands to confirm integration. Do not mark complete until all pass:
# 1. Check SDK is available (bundled or CDN)
grep -r "createClient\|WorkOS" src/ *.html 2>/dev/null || echo "FAIL: SDK not found"
# 2. Check createClient uses await
grep -rn "await createClient" src/ *.js *.html 2>/dev/null || echo "FAIL: createClient must be awaited"
# 3. Check sign-in is on user gesture (click handler)
grep -rn "signIn\|sign_in" src/ *.js *.html 2>/dev/null
# 4. Build succeeds (bundled projects only)
pnpm build 2>/dev/null || echo "CDN project — verify manually in browser"If check #2 fails: createClient() is async and must be awaited. Using it without await returns a Promise, not a client.
Environment Variables
Bundled projects only:
- Vite:
VITE_WORKOS_CLIENT_ID - Webpack:
REACT_APP_WORKOS_CLIENT_IDor custom - No
WORKOS_API_KEYneeded (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