Svelte

# Svelte 5 and SvelteKit Development Instructions

Instructions for building high-quality Svelte 5 and SvelteKit applications with modern runes-based reactivity, TypeScript, and performance optimization.

Project Context

- Svelte 5.x with runes system ($state, $derived, $effect, $props, $bindable)

- SvelteKit for full-stack applications with file-based routing

- TypeScript for type safety and better developer experience

- Component-scoped styling with CSS custom properties

- Progressive enhancement and performance-first approach

- Modern build tooling (Vite) with optimizations

Core Concepts

Architecture

- Use Svelte 5 runes system for all reactivity instead of legacy stores

- Organize components by feature or domain for scalability

- Separate presentation components from logic-heavy components

- Extract reusable logic into composable functions

- Implement proper component composition with slots and snippets

- Use SvelteKit's file-based routing with proper load functions

Component Design

- Follow single responsibility principle for components

- Use `<script lang="ts">` with runes syntax as default

- Keep components small and focused on one concern

- Implement proper prop validation with TypeScript annotations

- Use `{#snippet}` blocks for reusable template logic within components

- Use slots for component composition and content projection

- Pass `children` snippet for flexible parent-child composition

- Design components to be testable and reusable

Reactivity and State

Svelte 5 Runes System

- Use `$state()` for reactive local state management

- Implement `$derived()` for computed values and expensive calculations

- Use `$derived.by()` for complex computations beyond simple expressions

- Use `$effect()` sparingly - prefer `$derived` or function bindings for state sync

- Implement `$effect.pre()` for running code before DOM updates

- Use `untrack()` to prevent infinite loops when reading/writing same state in effects

- Define component props with `$props()` and destructuring with TypeScript annotations

- Use `$bindable()` for two-way data binding between components

- Migrate from legacy stores to runes for better performance

- Override derived values directly for optimistic UI patterns (Svelte 5.25+)

State Management

- Use `$state()` for local component state

- Implement type-safe context with `createContext()` helper over raw `setContext`/`getContext`

- Use context API for sharing reactive state down component trees

- Avoid global `$state` modules for SSR - use context to prevent cross-request data leaks

- Use SvelteKit stores for global application state when needed

- Keep state normalized for complex data structures

- Prefer `$derived()` over `$effect()` for computed values

- Implement proper state persistence for client-side data

Effect Best Practices

- **Avoid** using `$effect()` to synchronize state - use `$derived()` instead

- **Do** use `$effect()` for side effects: analytics, logging, DOM manipulation

- **Do** return cleanup functions from effects for proper teardown

- Use `$effect.pre()` when code must run before DOM updates (e.g., scroll position)

- Use `$effect.root()` for manually controlled effects outside component lifecycle

- Use `untrack()` to read state without creating dependencies in effects

- Remember: async code in effects doesn't track dependencies after `await`

SvelteKit Patterns

Routing and Layouts

- Use `+page.svelte` for page components with proper SEO

- Implement `+layout.svelte` for shared layouts and navigation

- Handle routing with SvelteKit's file-based system

Data Loading and Mutations

- Use `+page.server.ts` for server-side data loading and API calls

- Implement form actions in `+page.server.ts` for data mutations

- Use `+server.ts` for API endpoints and server-side logic

- Use SvelteKit's load functions for server-side and universal data fetching

- Implement proper loading, error, and success states

- Handle streaming data with promises in serve