the-collective-hub/.github/instructions/svelte5.instructions.md

description, applyTo

description	applyTo
Use when writing or editing Svelte components, reactive state, props, effects, or event handlers for The Collective Hub. Enforces Svelte 5 runes syntax and forbids legacy Svelte 4 patterns.	**/*.svelte

Svelte 5 Rules

Always Use Runes

Need	Use	Never
Local state	$state()	let x = 1 (mutable)
Computed value	$derived(expr)	$: x = expr
Side effects	$effect(() => { ... })	onMount (unless cleanup needed)
Component props	let { x } = $props()	export let x
Two-way bindable prop	$bindable()	—

<script lang="ts">
	let { label, value = $bindable('') }: { label: string; value?: string } = $props();
	let upper = $derived(value.toUpperCase());
</script>

Event Handlers

Use direct HTML event attributes — not on: directive syntax.

<!-- ✅ -->
<button onclick={handleClick}>Click</button>
<input oninput={(e) => (search = e.currentTarget.value)} />

<!-- ❌ -->
<button on:click={handleClick}>Click</button>

Composition: Snippets over Slots

<!-- ✅ -->
{#snippet row(item)}
	<tr><td>{item.name}</td></tr>
{/snippet}
{@render row(movie)}

<!-- ❌ -->
<slot name="row" />

To accept snippets as props: let { children } = $props() + {@render children()}.

Cross-Component State

• Prefer setContext / getContext for tree-scoped state
• Use .svelte.ts modules (with $state at module scope) for global/shared reactive state
• Avoid svelte/store (writable, readable, derived) in new code

Always

• <script lang="ts"> on every component
• Prefer $derived over $effect for computed values — $effect is for DOM/third-party side effects only

Deprecated APIs

<svelte:component> — Use component variables instead

<svelte:component> is deprecated in Svelte 5. Instead, assign a component constructor to a variable in the template using {@const} and render it directly as <ComponentVar />.

<!-- ❌ Deprecated in Svelte 5 -->
<svelte:component this={iconMap[key]} size={12} />

<!-- ✅ Svelte 5 approach -->
{@const Icon = iconMap[key]}
{#if Icon}
	<Icon size={12} />
{/if}

The {#if} guard ensures the component only renders when the variable is truthy, which also matches the previous runtime-guard behavior of <svelte:component>.

Code Quality

No svelte-ignore Suppression

svelte-ignore comments must NOT be used to suppress svelte-check errors or warnings. All accessibility (a11y), type, and other issues flagged by svelte-check must be fixed properly — never hidden behind a suppression comment.