CLAUDE.md for Svelte: 13 Rules That Stop AI From Writing React-Flavored Svelte

Reactive state uses plain variable assignment. No reactive() wrapper,
no useState(), no signal(). Mutate arrays and objects directly —
Svelte's compiler tracks assignments, not mutations.
Correct: items = [...items, newItem]
Incorrect: items.push(newItem) without reassignment

Cross-component state: Svelte stores (writable, readable, derived from svelte/store).
No external state library unless project explicitly requires it.
Subscribe with $ prefix in components — no manual subscribe/unsubscribe.
Store logic lives in src/lib/stores/ directory.

Side effects that need the DOM: onMount(). 
Cleanup: return a function from onMount().
No top-level await in component script unless using SvelteKit load functions.
onDestroy() for explicit cleanup when onMount return isn't enough.

Parent-to-child: export let propName (with default values where appropriate).
Child-to-parent: createEventDispatcher() and dispatch().
Sibling state: shared writable store.
No prop drilling beyond 2 levels — use store or context API.

(If using SvelteKit)
Page data: +page.server.ts load function — never fetch in onMount for initial data.
Layout data: +layout.server.ts.
Actions: form actions in +page.server.ts — no API routes for form submissions.
API endpoints: +server.ts only for non-form data needs.
No client-side fetch for data that can be server-loaded.

Entry/exit animations: svelte/transition (fade, fly, slide, scale, draw, crossfade).
Motion: svelte/motion (tweened, spring).
No external animation libraries for effects achievable with Svelte built-ins.
transition: directive on elements, not CSS class toggling.

Event handlers: on:event|modifier directive.
Modifiers: preventDefault, stopPropagation, once, passive — use the pipe syntax.
No addEventListener() in component script for DOM events on component elements.
Component events: on:custom-event directive at usage site.

(If Svelte 5+)
Content projection: snippets ({#snippet name()}{/snippet}) and {@render name()}.
No slots syntax in new components — snippets replace them.
(If Svelte 4)
Content projection: <slot> with named slots for multiple regions.

Derived values from reactive state: $: derivedValue = expression.
$: statements run when their dependencies change — order matters.
No manual watchers or watch() functions.
Complex derived logic: derived() store, not $: with side effects.

TypeScript: strict mode. All export let props typed explicitly.
Event dispatcher typed: createEventDispatcher<{eventName: PayloadType}>().
No implicit any on props.
Component generics (Svelte 5): use generics syntax where appropriate.

SSR-safe code only at module level.
window, document, localStorage: only inside onMount() or browser checks.
SvelteKit: use $app/environment browser flag for conditional client code.
No direct DOM manipulation outside lifecycle functions.

Component styles: scoped (default). No !important for component-scoped styles.
Global styles: :global() selector or app.css only — never in component <style> without :global().
CSS custom properties for theming — no inline style objects.
Class toggling: class:name={condition} directive, not string interpolation.

Unit tests: Vitest.
Component tests: @testing-library/svelte.
No Svelte-specific test utilities that wrap the component lifecycle unnecessarily.
Test files: component.test.ts colocated with component.
Stores: test logic by importing and setting store values directly.

# CLAUDE.md

## Stack
- Framework: Svelte 5 (or Svelte 4 — specify)
- Meta-framework: SvelteKit
- State: Svelte stores (writable/readable/derived)
- Styling: scoped CSS + CSS custom properties
- Testing: Vitest + @testing-library/svelte

## Reactivity rules
- Plain assignment for reactive state — no hooks, no refs
- $: for derived values — no manual watchers
- Mutate arrays/objects via reassignment, not mutation
- Cross-component state: writable stores with $ auto-subscription

## Component rules
- Props: export let propName — typed in TypeScript
- Events: createEventDispatcher, typed generics
- Lifecycle: onMount for DOM side effects, return cleanup function
- Transitions: svelte/transition built-ins — no external animation libs
- Events: on:event|modifier directive — no addEventListener in component script

## SvelteKit rules
- Initial data: server load functions, not onMount fetch
- Forms: form actions in +page.server.ts
- API: +server.ts for non-form endpoints only

## SSR safety
- window/document/localStorage: only inside onMount or browser checks
- No DOM access at module level

## Banned patterns
- useState(), useEffect(), ref() — wrong framework
- External state libraries unless explicitly required
- addEventListener() for component DOM events
- !important in component styles
- CSS class toggling via string interpolation (use class: directive)