81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# Svelte 5 Reactivity Safety (PARAMOUNT)
|
|
|
|
Svelte 5's reactive system triggers re-evaluation when it detects a new reference. Misuse causes infinite loops that pin CPU at 100%+.
|
|
|
|
## Rules
|
|
|
|
### `$derived` — NEVER create new objects or arrays
|
|
|
|
```typescript
|
|
// WRONG — .filter()/.map()/.reduce()/??[] create new references every evaluation
|
|
let messages = $derived(session?.messages ?? []); // new [] each time
|
|
let fileRefs = $derived(messages.filter(m => m.toolPath)); // new array each time
|
|
let grouped = $derived(items.reduce((a, i) => ..., {})); // new object each time
|
|
|
|
// RIGHT — plain getter functions called in template
|
|
function getMessages() { return session?.messages ?? EMPTY; }
|
|
function getFileRefs() { return getMessages().filter(m => m.toolPath); }
|
|
```
|
|
|
|
`$derived` is safe ONLY for primitives (`number`, `string`, `boolean`) or stable references (reading a field from a `$state` object).
|
|
|
|
### `$effect` — NEVER write to `$state` that the effect reads
|
|
|
|
```typescript
|
|
// WRONG — reads openDirs, writes openDirs → infinite loop
|
|
$effect(() => {
|
|
openDirs = new Set(openDirs); // read + write same $state
|
|
});
|
|
|
|
// WRONG — calls function that writes to $state
|
|
$effect(() => {
|
|
loadTasks(); // internally does ++pollToken which is $state
|
|
});
|
|
|
|
// RIGHT — use onMount for initialization
|
|
onMount(() => {
|
|
loadTasks();
|
|
openDirs = new Set([cwd]);
|
|
});
|
|
```
|
|
|
|
### `$effect` — NEVER use for async initialization
|
|
|
|
```typescript
|
|
// WRONG — async writes to $state during effect evaluation
|
|
$effect(() => {
|
|
loadData(); // writes to channels, agents, etc.
|
|
});
|
|
|
|
// RIGHT — onMount for all async init + side effects
|
|
onMount(() => {
|
|
loadData();
|
|
const timer = setInterval(poll, 30000);
|
|
return () => clearInterval(timer);
|
|
});
|
|
```
|
|
|
|
### Props that change frequently — NEVER pass as component props
|
|
|
|
```typescript
|
|
// WRONG — blinkVisible changes every 500ms → re-renders ENTIRE ProjectCard tree
|
|
<ProjectCard {blinkVisible} />
|
|
|
|
// RIGHT — store-based, only the leaf component (StatusDot) reads it
|
|
// blink-store.svelte.ts owns the timer
|
|
// StatusDot imports getBlinkVisible() directly
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
| Pattern | Safe? | Why |
|
|
|---------|-------|-----|
|
|
| `$derived(count + 1)` | Yes | Primitive, stable |
|
|
| `$derived(obj.field)` | Yes | Stable reference |
|
|
| `$derived(arr.filter(...))` | **NO** | New array every eval |
|
|
| `$derived(x ?? [])` | **NO** | New `[]` when x is undefined |
|
|
| `$derived(items.map(...))` | **NO** | New array + new objects |
|
|
| `$effect(() => { state = ... })` | **NO** | Write triggers re-run |
|
|
| `$effect(() => { asyncFn() })` | **NO** | Async writes to state |
|
|
| `onMount(() => { state = ... })` | Yes | Runs once, no re-trigger |
|
|
| Plain function in template | Yes | Svelte tracks inner reads |
|