WorkOS AuthKit for SvelteKit

Step 1: Fetch SDK Documentation (BLOCKING)

STOP. Do not proceed until complete.

WebFetch: https://github.com/workos/authkit-sveltekit/blob/main/README.md

The README is the source of truth. If this skill conflicts with README, follow README.

Step 2: Pre-Flight Validation

Project Structure

• Confirm svelte.config.js (or svelte.config.ts) exists
• Confirm package.json contains @sveltejs/kit dependency
• Confirm src/routes/ directory exists

Environment Variables

Check .env or .env.local for:

• WORKOS_API_KEY - starts with sk_
• WORKOS_CLIENT_ID - starts with client_
• WORKOS_REDIRECT_URI - valid callback URL
• WORKOS_COOKIE_PASSWORD - 32+ characters

SvelteKit uses $env/static/private and $env/dynamic/private natively. The agent should write env vars to .env (SvelteKit's default) or .env.local.

Step 3: Install SDK

Detect package manager, install SDK package from README.

pnpm-lock.yaml? → pnpm add @workos-inc/authkit-sveltekit
yarn.lock? → yarn add @workos-inc/authkit-sveltekit
bun.lockb? → bun add @workos-inc/authkit-sveltekit
else → npm install @workos-inc/authkit-sveltekit

Verify: SDK package exists in node_modules before continuing.

Step 4: Configure Server Hooks

SvelteKit uses src/hooks.server.ts for server-side middleware. This is where the AuthKit handler is registered.

Create or update src/hooks.server.ts with the authkit handle function from the README.

Existing Hooks (IMPORTANT)

If src/hooks.server.ts already exists with custom logic, use SvelteKit's sequence() helper to compose hooks:

import { sequence } from '@sveltejs/kit/hooks';
import { authkitHandle } from '@workos-inc/authkit-sveltekit'; // Check README for exact export

export const handle = sequence(authkitHandle, yourExistingHandle);

Check README for the exact export name and usage pattern.

Step 5: Create Callback Route

Parse WORKOS_REDIRECT_URI to determine route path:

URI path          --> Route location
/callback         --> src/routes/callback/+server.ts
/auth/callback    --> src/routes/auth/callback/+server.ts

Use the SDK's callback handler from the README. Do not write custom OAuth logic.

Critical: SvelteKit uses +server.ts for API routes, not +page.server.ts.

Step 6: Layout Setup

Update src/routes/+layout.server.ts to load the auth session and pass it to all pages.

Check README for the exact pattern — typically a load function that returns the user session from locals.

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async (event) => {
  // Check README for exact API — session is typically on event.locals
  return {
    user: event.locals.user, // or similar from README
  };
};

Step 7: UI Integration

Add auth UI to src/routes/+page.svelte using the session data from the layout.

• Show user info when authenticated
• Show sign-in link/button when not authenticated
• Add sign-out functionality

Check README for sign-in URL generation and sign-out patterns.

Verification Checklist (ALL MUST PASS)

Run these commands to confirm integration. Do not mark complete until all pass:

# 1. Check hooks.server.ts exists and has authkit
grep -i "workos\|authkit" src/hooks.server.ts || echo "FAIL: authkit missing from hooks.server.ts"

# 2. Check callback route exists
find src/routes -name "+server.ts" -path "*/callback/*"

# 3. Check layout loads auth session
grep -i "user\|auth\|session" src/routes/+layout.server.ts || echo "FAIL: auth session missing from layout"

# 4. Build succeeds
pnpm build || npm run build

Error Recovery

"Cannot find module '@workos-inc/authkit-sveltekit'"

• Check: SDK installed before writing imports
• Check: SDK package directory exists in node_modules
• Re-run install if missing

hooks.server.ts not taking effect

• Check: File is at src/hooks.server.ts, not src/hooks.ts or elsewhere
• Check: Named export is handle (SvelteKit requirement)
• Check: If using sequence(), all handles are properly composed

Callback route not found (404)

• Check: File uses +server.ts (not +page.server.ts)
• Check: Route path matches WORKOS_REDIRECT_URI path exactly
• Check: Exports GET handler (SvelteKit convention)

"locals" type errors

• Check: App.Locals interface is augmented in src/app.d.ts
• Check README for TypeScript setup instructions

Cookie password error

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

Auth state not available in pages

• Check: +layout.server.ts load function returns user data
• Check: Pages access data via export let data (Svelte 4) or $page.data (Svelte 5)