Svelte SvelteKit Agent Rules
Project Context
- Use SvelteKit with Svelte 5 and TypeScript in `strict` mode throughout.
- Follow SvelteKit file conventions: `+page.svelte`, `+page.ts`, `+page.server.ts`, `+layout.svelte`, `+error.svelte`.
- Use `src/lib/` for shared utilities and components; import via `$lib/` alias.
- Prefer server-side data loading and form actions over client-side fetch and state.
Code Style & Structure
- Use `<script lang="ts">` in all Svelte components. Enable strict TypeScript checking.
- Follow kebab-case for file names. Use PascalCase for component names.
- Keep components focused and under 150 lines. Extract reusable logic into `$lib/utils/`.
- Use `$lib/server/` for server-only utilities (DB access, secrets) — SvelteKit prevents client bundling of these.
Svelte 5 Runes
- Use `$state()` for reactive local state — replaces `let` reactive declarations from Svelte 4.
- Use `$derived()` for computed values that depend on reactive state — replaces `$:` reactive statements.
- Use `$effect()` for side effects that respond to state changes. Keep effects minimal.
- Use `$props()` to declare typed component props with default values: `let { title = 'Default' }: Props = $props()`.
- Use `$bindable()` for two-way binding props. Prefer one-way data flow when possible.
- Use snippet blocks (`{#snippet name()}`) and `{@render name()}` for composable template fragments.
Data Loading
- Use `+page.ts` for universal load functions that run on both server and client.
- Use `+page.server.ts` for server-only loading — database queries, authenticated fetches, secrets.
- Type load functions with `PageLoad` and `PageServerLoad` from `./$types` for full inference.
- Access loaded data in components via `let { data } = $props()` with the `PageData` type.
- Use `depends('app:resource')` and `invalidate('app:resource')` for fine-grained cache invalidation.
- Throw `error(404, 'Not found')` from `@sveltejs/kit` for expected HTTP errors in load functions.
- Use the `fetch` parameter from the load function for server-side requests with automatic cookie forwarding.
Form Actions
- Use SvelteKit form actions (`actions` export in `+page.server.ts`) for all mutations — not client-side fetch.
- Apply `use:enhance` on `<form>` elements to progressively enhance without full-page reloads.
- Validate form data server-side with Zod or Valibot schemas before processing.
- Return validation errors from actions using `fail(422, { errors })` with typed field-level error objects.
- Use `applyAction` inside a custom `enhance` callback for redirect, reset, and toast behavior.
- Name multiple actions on one page: `?/create`, `?/update`, `?/delete`.
State Management
- Prefer server-side state via load functions over client stores for page-level data.
- Use Svelte stores (`writable`, `readable`, `derived`) only for cross-component client UI state.
- Use URL search params for shareable and bookmarkable UI state (filters, sort, pagination).
- Use `setContext` and `getContext` for component-tree-scoped state — avoid global stores for local concerns.
- Use Pinia or Zustand only if you need complex store features like middleware or devtools.
Hooks & Middleware
- Use `hooks.server.ts` for global request handling: authentication, logging, security headers, CSP.
- Set `event.locals.user` in server hooks — access it in all subsequent load functions and actions.
- Use `handleFetch` in hooks to modify outgoing fetch calls (add auth headers for server-side requests).
- Handle server errors in `hooks.server.ts` with the `handleError` export for structured error logging.
Error Handling
- Implement `+error.svelte` at each route group level for contextual error UIs.
- Distinguish between `error()` (expected HTTP errors) and unexpected errors in error pages.
- Validate all user inputs server-side in actions and API routes — never trust client-provided data.
- Use `locals` set in hooks for per-request user context; never pass sensitive data through URL params.
Performance
- Use `data-sveltekit-preload-data` on links for instant page transitions using prefetched data.
- Return `Promise` values from load functions to enable streaming with `<svelte:boundary>` and `{#await}`.
- Use `@sveltejs/enhanced-img` or `vite-imagetools` for automatic image optimization at build time.
- Keep client-side JavaScript minimal — Svelte compiles to vanilla JS with no runtime framework overhead.
Testing
- Write unit tests with Vitest for utility functions, stores, and logic modules in `src/lib/`.
- Use `@testing-library/svelte` for component rendering and interaction tests.
- Test load functions and form actions as plain async functions by constructing mock event objects.
- Use Playwright for end-to-end tests of critical user flows including form submissions.
TypeScript/
SvelteKit