workos-authkit-vanilla-js

Original：🇺🇸 English

Not Translated

Integrate WorkOS AuthKit with vanilla JavaScript applications. No framework required, browser-only. Use when project is plain HTML/JS, doesn't use React/Vue/etc, or mentions vanilla JavaScript authentication.

1installs

Sourceworkos/skills

Added on2026-02-10

NPX Install

npx skill4agent add workos/skills workos-authkit-vanilla-js

SKILL.md Content

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.

javascript

// 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