WorkOS AuthKit Base Template

First Action: Fetch README

Before any implementation, fetch the framework-specific README:

WebFetch: {sdk-package-name} README from npmjs.com or GitHub

README is the source of truth for: install commands, imports, API usage, code patterns.

Task Structure (Required)

Phase	Task	Blocked By	Purpose
1	preflight	-	Verify env vars, detect framework
2	install	preflight	Install SDK package
3	callback	install	Create OAuth callback route
4	provider	install	Setup auth context/middleware
5	ui	callback, provider	Add sign-in/out UI
6	verify	ui	Build confirmation

Decision Trees

Package Manager Detection

pnpm-lock.yaml? → pnpm
yarn.lock? → yarn
bun.lockb? → bun
else → npm

Provider vs Middleware

Client-side framework? → AuthKitProvider wraps app
Server-side framework? → Middleware handles sessions
Hybrid (Next.js)? → Both may be needed

Callback Route Location

Extract path from WORKOS_REDIRECT_URI → create route at that exact path.

Environment Variables

Variable	Purpose	When Required
WORKOS_API_KEY	Server authentication	Server SDKs
WORKOS_CLIENT_ID	Client identification	All SDKs
WORKOS_REDIRECT_URI	OAuth callback URL	Server SDKs
WORKOS_COOKIE_PASSWORD	Session encryption (32+ chars)	Server SDKs

Note: Some frameworks use prefixed variants (e.g., NEXT_PUBLIC_*). Check README.

Verification Checklists

After Install

• SDK package installed in node_modules
• No install errors in output

After Callback Route

• Route file exists at path matching WORKOS_REDIRECT_URI
• Imports SDK callback handler (not custom OAuth)

After Provider/Middleware

• Provider wraps entire app (client-side)
• Middleware configured in correct location (server-side)

After UI

• Home page shows conditional auth state
• Uses SDK functions for sign-in/out URLs

Final Verification

• Build completes with exit code 0
• No import resolution errors

Error Recovery

Module not found

• Verify install completed successfully
• Verify SDK exists in node_modules
• Re-run install if missing

Build import errors

• Delete node_modules, reinstall
• Verify package.json has SDK dependency

Invalid redirect URI

• Compare route path to WORKOS_REDIRECT_URI
• Paths must match exactly

Cookie password error

• Verify WORKOS_COOKIE_PASSWORD is 32+ characters
• Generate new: openssl rand -base64 32

Auth state not persisting

• Verify provider wraps entire app
• Check middleware is in correct location

Critical Rules

1. Install SDK before writing imports - never create import statements for uninstalled packages
2. Use SDK functions - never construct OAuth URLs manually
3. Follow README patterns - SDK APIs change between versions
4. Extract callback path from env - don't hardcode /auth/callback