programming-svelte— agent skill

Mental model

Svelte 5 compiles components to small, efficient updates; SvelteKit adds routing, server-side rendering, and form actions on top. The Svelte advantage is its compiler — most apps need very little client state management, no global store libraries, and no useEffect-style synchronization. Most maintenance trouble comes from importing React habits: pushing everything client-side, manual derived state, and effects doing the job of derivations.

Runes (Svelte 5)

• $state(...) for reactive local state — replaces top-level let reactivity
• $derived(...) for computed values — replaces the old $: reactive blocks; deep dependency tracking is automatic
• $effect(...) for side effects only (DOM, subscriptions, non-Svelte libraries) — never for derived values
• $props() for typed component props; $bindable() for two-way bindable props
• Runes work in .svelte.ts / .svelte.js files too — extract reactive logic into modules
• Avoid effects that read state and write state — they create loops and obscure data flow

Component design

• One component per .svelte file; <script lang="ts"> → markup → <style> ordering
• Props are an API — type them with $props<{...}>() and document defaults
• Snippets (Svelte 5) replace slots for reusable markup with parameters
• Keep components small; extract sub-components when sections have their own state or events
• Scoped styles by default — global styles only via :global(...) when intentional

SvelteKit architecture

• File-based routing in src/routes/: +page.svelte (page), +layout.svelte (shared layout), +page.ts / +page.server.ts (load), +server.ts (API endpoints)
• +page.server.ts runs only on the server — safe for database queries, secrets, server-only deps
• +page.ts runs on both server and client (universal) — pure data fetching that can hydrate
• load functions return data the page renders; throw redirect() / error() for control flow
• Layouts compose; place shared data loading at the layout level and child pages inherit via $page.data
• hooks.server.ts for cross-cutting concerns: auth, request logging, CSRF, response headers

Forms and mutations

• Form actions (+page.server.ts actions = { default: ... }) for mutations — progressive-enhancement friendly, work without JS
• use:enhance upgrades the form to a fetch-driven submission with optimistic updates
• Validate on the server; share validation schemas (zod/valibot) between client and server when both validate
• Return validation errors from actions; the page renders them via form prop
• Use API endpoints (+server.ts) for non-form mutations, third-party integrations, or non-HTML responses

State management

• Local reactive state with $state covers most needs — no global store library required for typical apps
• Cross-component shared state: a module exporting a $state object, imported where needed
• The $page store and SvelteKit's goto/invalidate cover URL-driven state and re-fetching
• Persist state in URL search params, cookies, or localStorage — not in long-lived module-level reactive state across navigations
• Avoid the legacy writable/readable/derived stores for new code unless interop demands them — runes replace them

Server/client boundary

• Server-only code lives in +page.server.ts, +server.ts, +layout.server.ts, and $lib/server/ — anything else may be bundled to the client
• Secrets and server-only modules go behind the $lib/server/ boundary; SvelteKit fails the build if they leak to client code
• Environment variables: $env/static/private (server, build-time), $env/static/public (client-safe, build-time), $env/dynamic/* (runtime)
• Stream data with await streamed.foo in load functions — page renders progressively without blocking on slow data

Performance

• Svelte's compiler already optimizes updates — micro-optimizations are rarely needed
• Code-split happens at route boundaries automatically
• Lazy-load heavy components with dynamic import() when they're conditionally rendered
• Use {#key value}{/key} to force a subtree to recreate when identity changes

Testing

• Vitest for unit and component logic
• @testing-library/svelte for component tests — query by role and text, not by component internals
• Playwright for end-to-end flows — particularly important for form actions and progressive enhancement paths
• Mock at the network layer (MSW) rather than mocking fetch

Project layout

• src/lib/ for reusable code ($lib alias); src/lib/server/ for server-only modules
• Feature folders inside src/lib/ when the app grows; routes stay slim and import features
• Components, types, and utilities colocated by feature, not split by kind