Svelte Guidelines

Reference Repositories

• Svelte — Svelte 5 framework with runes and fine-grained reactivity
• shadcn-svelte — Port of shadcn/ui for Svelte with Bits UI primitives
• shadcn-svelte-extras — Additional components for shadcn-svelte

Related Skills: See query-layer for TanStack Query integration. See styling for CSS and Tailwind conventions.

When to Apply This Skill

Use this pattern when you need to:

• Build Svelte 5 components that use TanStack Query mutations.
• Replace nested ternary $derived mappings with satisfies Record lookups.
• Decide between createMutation in .svelte and .execute() in .ts.
• Follow shadcn-svelte import, composition, and component organization patterns.
• Refactor one-off handle* wrappers into inline template actions.
• Convert SvelteMap data to arrays for derived state or component props.

References

Load these on demand based on what you're working on:

• If working with TanStack Query mutations (createMutation, .execute(), onSuccess/onError), read references/tanstack-query-mutations.md
• If working with shadcn-svelte components (imports, composition, styling, customization), read references/shadcn-patterns.md
• If working with reactive state modules (fromTable, fromKv, $derived arrays, state factories), read references/reactive-state-pattern.md
• If working with component architecture (props, inlining handlers, self-contained components, view-mode branching, data-driven markup), read references/component-patterns.md
• If working with loading or empty states (Spinner, Empty.*, {#await} blocks), read references/loading-empty-states.md

---

$derived Value Mapping: Use satisfies Record, Not Ternaries

When a $derived expression maps a finite union to output values, use a satisfies Record lookup. Never use nested ternaries. Never use $derived.by() with a switch just to map values.

<!-- Bad: nested ternary in $derived -->
<script lang="ts">
	const tooltip = $derived(
		syncStatus.current === 'connected'
			? 'Connected'
			: syncStatus.current === 'connecting'
				? 'Connecting…'
				: 'Offline',
	);
</script>

<!-- Bad: $derived.by with switch for a pure value lookup -->
<script lang="ts">
	const tooltip = $derived.by(() => {
		switch (syncStatus.current) {
			case 'connected': return 'Connected';
			case 'connecting': return 'Connecting…';
			case 'offline': return 'Offline';
		}
	});
</script>

<!-- Good: $derived with satisfies Record -->
<script lang="ts">
	import type { SyncStatus } from '@epicenter/sync-client';

	const tooltip = $derived(
		({
			connected: 'Connected',
			connecting: 'Connecting…',
			offline: 'Offline',
		} satisfies Record<SyncStatus, string>)[syncStatus.current],
	);
</script>

Why satisfies Record wins:

• Compile-time exhaustiveness: add a value to the union and TypeScript errors on the missing key. Nested ternaries silently fall through.
• It's a data declaration, not control flow. The mapping is immediately visible.
• $derived() stays a single expression — no need for $derived.by().

Reserve $derived.by() for multi-statement logic where you genuinely need a function body. For value lookups, keep it as $derived() with a record.

as const is unnecessary when using satisfies. satisfies Record<T, string> already validates shape and value types.

See docs/articles/record-lookup-over-nested-ternaries.md for rationale.

When to Use SvelteMap vs $state

Use SvelteMap when items have stable IDs and you need keyed lookup. Use $state for primitives, local UI booleans, and sequential data without identity.

Data Shape	Use	Example
Workspace table rows (have IDs)	fromTable() → SvelteMap	recordings, conversations, notes
Workspace KV (single key)	fromKv()	selectedFolderId, sortBy
Browser API keyed data	new SvelteMap() + listeners	Chrome tabs, windows
Primitive value	$state(value)	$state(false), $state(''), $state(0)
Sequential data without IDs	$state<T[]>([])	terminal history, command history
Ordered list where position matters	$state<T[]>([])	open file tab order

Anti-Pattern: $state for ID-Keyed Collections

// ❌ BAD: O(n) lookups, coarse reactivity, referential instability
let conversations = $state<Conversation[]>(readAll());
const metadata = $derived(conversations.find((c) => c.id === id)); // O(n) scan

// ✅ GOOD: O(1) lookups, per-key reactivity, stable $derived array
const conversationsMap = fromTable(workspace.tables.conversations);
const conversations = $derived(
	conversationsMap.values().toArray().sort((a, b) => b.updatedAt - a.updatedAt),
);
const metadata = $derived(conversationsMap.get(id)); // O(1) lookup

Three problems with $state<T[]> for keyed data:

1. O(n) lookups — every .find() scans the whole array
2. Coarse reactivity — updating one item re-triggers everything reading the array
3. Referential instability — sorting in a getter creates a new array every access, causing TanStack Table infinite loops

See docs/articles/sveltemap-over-state-for-keyed-collections.md for the full rationale.

Reactive Table State Pattern

When a factory function exposes workspace table data via fromTable, follow this three-layer convention:

// 1. Map — reactive source (private, suffixed with Map)
const foldersMap = fromTable(workspaceClient.tables.folders);

// 2. Derived array — cached materialization (private, no suffix)
const folders = $derived(foldersMap.values().toArray());

// 3. Getter — public API (matches the derived name)
return {
	get folders() {
		return folders;
	},
};

Naming: {name}Map (private source) → {name} (cached derived) → get {name}() (public getter).

With Sort or Filter

Chain operations inside $derived — the entire pipeline is cached:

const tabs = $derived(tabsMap.values().toArray().sort((a, b) => b.savedAt - a.savedAt));
const notes = $derived(allNotes.filter((n) => n.deletedAt === undefined));

See the typescript skill for iterator helpers (.toArray(), .filter(), .find() on IteratorObject).

Template Props

For component props expecting T[], derive in the script block — never materialize in the template:

<!-- Bad: re-creates array on every render -->
<FujiSidebar entries={entries.values().toArray()} />

<!-- Good: cached via $derived -->
<script>
	const entriesArray = $derived(entries.values().toArray());
</script>
<FujiSidebar entries={entriesArray} />

Why $derived, Not a Plain Getter

Put reactive computations in $derived, not inside public getters.

A getter may still be reactive if it reads reactive state, but it recomputes on every access. $derived computes reactively and caches until dependencies change.

Use $derived for the computation. Use the getter only as a pass-through to expose that derived value.

See docs/articles/derived-vs-getter-caching-matters.md for rationale.

Reactive State Module Conventions

State modules use a factory function that returns a flat object with getters and methods, exported as a singleton.

function createBookmarkState() {
	const bookmarksMap = fromTable(workspaceClient.tables.bookmarks);
	const bookmarks = $derived(bookmarksMap.values().toArray());

	return {
		get bookmarks() { return bookmarks; },
		async add(tab: Tab) { /* ... */ },
		remove(id: BookmarkId) { /* ... */ },
	};
}

export const bookmarkState = createBookmarkState();

Naming

Concern	Convention	Example
Export name	xState for domain state; descriptive noun for utilities	bookmarkState, notesState, deviceConfig, vadRecorder
Factory function	createX() matching the export name	createBookmarkState()
File name	Domain name, optionally with -state suffix	bookmark-state.svelte.ts, auth.svelte.ts

Use the State suffix when the export name would collide with a key property (bookmarkState.bookmarks, not bookmarks.bookmarks).

Accessor Patterns

Data Shape	Accessor	Example
Collection	Named getter	bookmarkState.bookmarks, notesState.notes
Single reactive value	.current (Svelte 5 convention)	selectedFolderId.current, serverUrl.current
Keyed lookup	.get(key)	toolTrustState.get(name), deviceConfig.get(key)

The .current convention comes from runed (the standard Svelte 5 utility library). All 34+ runed utilities use .current. Never use .value (Vue convention).

Persisted State Utilities

For localStorage/sessionStorage persistence, use createPersistedState (single value) or createPersistedMap (typed multi-key config) from @epicenter/svelte.

// Single value — .current accessor
import { createPersistedState } from '@epicenter/svelte'