sveltekit-spa: Instructions file for Claude Code

SvelteKit SPA — Project Rules

SvelteKit (latest) + Runes + TypeScript + Supabase Auth + Postgres + shadcn-svelte.

Follow these rules when generating or editing code in this repo. General coding behavior (simplicity, surgical changes, surfacing assumptions) is covered by the karpathy-guidelines skill and is not repeated here.

This project runs in SPA mode (ssr = false, adapter-static). All code executes in the browser. There are no server routes, server hooks, or server-side rendering.

MCP usage (required)

Two MCP servers are configured in .mcp.json:

• Svelte MCP — use whenever Svelte/SvelteKit development is involved.
  • Run list-sections first, review use_cases, then fetch ALL relevant sections via get-documentation.
  • Run svelte-autofixer whenever writing or editing Svelte code, and keep running it until no issues or suggestions remain.
  • Use playground-link only when explicitly asked for a playground link, and never when code is being written directly to project files.
• Supabase MCP — use for database/auth inspection and project context. Configured read_only=true.
  • Do not run mutating operations (writes, deletes, schema changes) unless explicitly requested.
  • Requires OAuth. Run /mcp to authenticate.

1) SvelteKit conventions

• Use SvelteKit file conventions correctly:
  • Route components: +page.svelte, layouts: +layout.svelte, data: +page.ts/+layout.ts.
  • Avoid putting business logic in route files; move reusable logic to src/lib.
• In SPA mode (ssr = false), do not rely on server-only behavior. Keep Supabase client-side with browser-safe env vars only.
• Use $app/navigation (goto) and $app/state (page, navigating, updated) for routing concerns.
  • NEVER use deprecated $app/stores — it's for legacy SvelteKit <2.12 only.
  • Import page from $app/state: import { page } from '$app/state'
  • Use page.url.pathname directly (no $ prefix needed — it's already reactive with runes).
• Redirects/guards must be done in layouts for sections (e.g., protected area), not sprinkled across many pages.
• Never compare pathnames with raw string equality — SvelteKit may add or omit trailing slashes.
  • Always normalize paths before comparing (strip trailing slash if length > 1).
  • Prefer comparing parsed identifiers (e.g., step numbers, route params) over raw pathname strings.
• Load function invalidation with depends/invalidate:
  • When a +layout.ts or +page.ts load function depends on auth state, call depends('auth:session') inside it so it can be re-run on demand.
  • After login, logout, or any auth state change, call invalidate('auth:session') (from $app/navigation) to trigger re-runs of every load function that declared the dependency.
  • This keeps load functions reactive to auth changes without sprinkling manual checks across pages.
  • The dependency key is a custom string — not a URL. SvelteKit matches it by exact string equality.