workos-authkit-react

Original：🇺🇸 English

Translated

Integrate WorkOS AuthKit with React single-page applications. Client-side only authentication. Use when the project is a React SPA without Next.js or React Router.

3installs

Sourceworkos/skills

Added on2026-03-04

NPX Install

npx skill4agent add workos/skills workos-authkit-react

SKILL.md Content

View Translation Comparison →

WorkOS AuthKit for React (SPA)

Decision Tree

START
  │
  ├─► Fetch README (BLOCKING)
  │   github.com/workos/authkit-react/blob/main/README.md
  │   README is source of truth. Stop if fetch fails.
  │
  ├─► Detect Build Tool
  │   ├─ vite.config.ts exists? → Vite
  │   └─ otherwise → Create React App
  │
  ├─► Set Env Var Prefix
  │   ├─ Vite → VITE_WORKOS_CLIENT_ID
  │   └─ CRA  → REACT_APP_WORKOS_CLIENT_ID
  │
  └─► Implement per README

Critical: Build Tool Detection

Marker File	Build Tool	Env Prefix	Access Pattern
`vite.config.ts`	Vite	`VITE_`	`import.meta.env.VITE_*`
`craco.config.js` or none	CRA	`REACT_APP_`	`process.env.REACT_APP_*`

Wrong prefix = undefined values at runtime. This is the #1 integration failure.

Key Clarification: No Callback Route

The React SDK handles OAuth callbacks internally via AuthKitProvider.

No server-side callback route needed
SDK intercepts redirect URI client-side
Token exchange happens automatically

Just ensure redirect URI env var matches WorkOS Dashboard exactly.

Required Environment Variables

{PREFIX}WORKOS_CLIENT_ID=client_...
{PREFIX}WORKOS_REDIRECT_URI=http://localhost:5173/callback

WORKOS_API_KEY

needed. Client-side only SDK.

Verification Checklist

README fetched and read
Build tool detected correctly
Env var prefix matches build tool
```
.env
```
or
```
.env.local
```
has required vars
No
```
next
```
dependency (wrong skill)
No
```
react-router
```
dependency (wrong skill)
AuthKitProvider wraps app root
```
pnpm build
```
exits 0

Error Recovery

"clientId is required"

Cause: Env var inaccessible (wrong prefix)

Check: Does prefix match build tool? Vite needs

VITE_

, CRA needs

REACT_APP_

Auth state lost on refresh

Cause: Token persistence issue

Check: Browser dev tools → Application → Local Storage. SDK stores tokens here automatically.

useAuth returns undefined

Cause: Component outside provider tree

Check: Entry file (

main.tsx

index.tsx

) wraps

<App />

<AuthKitProvider>

Callback redirect fails

Cause: URI mismatch

Check: Env var redirect URI exactly matches WorkOS Dashboard → Redirects configuration.