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 withawait- 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_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