By name: svelte description: "[Applies to: **/*.{svelte,js,ts}] Definitive guide for writing clean, performant, and maintainable Svelte 5 applications using the runes API and modern TypeScript practices." source: "cursor_mdc"
Svelte Best Practices (Svelte 5 + TypeScript)
This guide outlines the definitive best practices for developing Svelte 5 applications with TypeScript. We prioritize explicit reactivity, strong typing, and compiler-driven performance.
1. Code Organization and Structure
Always structure your Svelte components for clarity and maintainability.
1.1. HTML-First Component Design
Keep your component logic, markup, and styles co-located within the .svelte file. This is Svelte's core philosophy.
❌ BAD: Over-abstracting into separate JS files for simple logic
<!-- MyComponent.svelte -->
<script lang="ts">
import { calculateValue } from './utils'; // Unnecessary abstraction
let count = $state(0);
let computed = $derived(calculateValue(count));
</script>
✅ GOOD: Keep related logic within the component
<!-- MyComponent.svelte -->
<script lang="ts">
let count = $state(0);
let computed = $derived(count * 2 + 1); // Simple logic stays here
</script>
1.2. TypeScript Everywhere
Use lang="ts" in all <script> tags. Configure svelte-check in CI and use the VS Code extension for real-time feedback.
❌ BAD: Missing lang="ts"
<script>
let name: string = 'world'; // No type checking
</script>
✅ GOOD: Explicitly enable TypeScript
<script lang="ts">
let name: string = 'world'; // Full type safety
</script>
2. Component Architecture (Svelte 5 Runes)
Svelte 5's runes API makes reactivity explicit and powerful. Embrace it fully.
2.1. Explicit Reactive State with $state
Declare all reactive state using $state. This makes your component's reactivity clear and refactor-friendly.
❌ BAD: Implicit reactivity (Svelte 4 style)
<script lang="ts">
let count = 0; // Not reactive outside top-level
function increment() { count++; }
</script>
✅ GOOD: Explicit $state for all reactive variables
<script lang="ts">
let count = $state(0); // Clearly reactive
function increment() { count++; }
</script>
2.2. Derived State with $derived
Use $derived for any value that is a pure computation of other reactive state.
❌ BAD: $effect or $: for derived values
<script lang="ts">
let count = $state(0);
$effect(() => { // Incorrectly using effect for derivation
console.log('Count changed:', count);
// This is a side effect, not a derivation
});
$: doubled = count * 2; // Svelte 4 style, less explicit
</script>
✅ GOOD: $derived for pure computations
<script lang="ts">
let count = $state(0);
let doubled = $derived(count * 2); // Clearly a derived value
</script>
2.3. Side Effects with $effect
Reserve $effect for actual side effects (e.g., DOM manipulation, API calls, logging).
❌ BAD: Mixing derivations and effects
<script lang="ts">
let count = $state(0);
$: if (count > 5) { // Svelte 4 style, combines derivation and effect
alert('Count is too high!');
}
</script>
✅ GOOD: Clear separation of concerns
<script lang="ts">
let count = $state(0);
$effect(() => { // Clearly a side effect
if (count > 5) {
alert('Count is too high!');
}
});
</script>
2.4. Component Properties with $props
Declare all component properties using the $props() rune and destructuring. This provides powerful type safety and flexibility.
❌ BAD: export let (Svelte 4 style)
<script lang="ts">
export let name: string;
export let age: number = 30;
</script>
✅ GOOD: $props() for properties
<script lang="ts">
interface Props {
name: string;
age?: number; // Optional prop
}
let { name, age = 30 }: Props = $props();
</script>
2.5. Event Handling
Remove the on: prefix for event handlers. They are now standard properties.
❌ BAD: on:click
<button on:click={() => alert('Clicked!')}>Click me</button>
✅ GOOD: onclick (standard HTML attribute)
<button onclick={() => alert('Clicked!')}>Click me</button>
2.6. Slots and Snippets
Use {@render} for rendering slots and snippets, providing type safety and better control over content.
❌ BAD: Untyped slots
<!-- MyComponent.svelte -->
<slot />
✅ GOOD: Typed snippets for predictable content
<!-- MyComponent.svelte -->
<script lang="ts">
import type { Snippet } from 'svelte';
let { header }: { header: Snippet } = $props();
</script>
<div>
{@render header()}
<slot />
</div>
3. State Management
Prioritize local component state with $state. Use Svelte stores for truly global or complex cross-component state.
3.1. Local State First
Most state should live within the component using $state.
❌ BAD: Over-reliance on global stores for simple component state
// store.ts
import { writable } from 'svelte/store';
export const localCounter = writable(0); // Unnecessary global
✅ GOOD: Use $state for component-local reactivity
<script lang="ts">
let count = $state(0); // Local to this component
</script>
3.2. Svelte Stores for Global State
For state shared across many components or complex application-wide state, use Svelte's built-in stores.
// src/lib/stores/auth.ts
import { writable } from 'svelte/store';
export const isAuthenticated = writable(false);
export const user = writable<{ id: string; name: string } | null>(null);
<!-- AuthStatus.svelte -->
<script lang="ts">
import { isAuthenticated, user } from '$lib/stores/auth';
</script>
{#if $isAuthenticated}
<p>Welcome, {$user?.name}!</p>
{:else}
<p>Please log in.</p>
{/if}
4. Performance Considerations
SvelteKit handles many optimizations automatically. Supplement these with mindful coding.
4.1. {#each} with Keys
Always provide a unique key to {#each} blocks for efficient DOM updates.
❌ BAD: Missing key
{#each items as item}
<ItemComponent {item} />
{/each}
✅ GOOD: Use a unique key
{#each items as item (item.id)}
<ItemComponent {item} />
{/each}
4.2. Dynamic Imports for Lazy Loading
Lazy-load components or modules that aren't immediately needed to reduce initial bundle size.
<script lang="ts">
let showModal = $state(false);
async function openModal() {
const { default: Modal } = await import('./Modal.svelte');
// Render Modal component
showModal = true;
}
</script>
{#if showModal}
<Modal />
{/if}
<button onclick={openModal}>Open Modal</button>
5. Common Pitfalls and Gotchas
Avoid these common mistakes to ensure robust and predictable Svelte applications.
5.1. Misunderstanding $effect Dependencies
$effect runs when its dependencies change. Be explicit about what it depends on.
❌ BAD: Implicit dependencies or missing cleanup
<script lang="ts">
let count = $state(0);
$effect(() => {
// This effect might not re-run if `count` isn't directly used
// or if `doSomething` has internal state changes not tracked by Svelte.
doSomething(count);
});
</script>
✅ GOOD: Explicit dependencies and cleanup
<script lang="ts">
let count = $state(0);
$effect(() => {
const timer = setInterval(() => {
console.log('Count is', count); // `count` is a dependency
}, 1000);
return () => clearInterval(timer); // Cleanup function
});
</script>
5.2. Forgetting generics Attribute
When creating generic components, remember to add the generics attribute to the <script> tag.
❌ BAD: Untyped generic props
<script lang="ts">
interface Props { items: any[]; } // Loses type safety
let { items }: Props = $props();
</script>
✅ GOOD: Explicit generics for type safety
<script lang="ts" generics="Item extends { id: string }">
interface Props { items: Item[]; }
let { items }: Props = $props();
</script>
6. Accessibility
Build accessible Svelte applications by default.
6.1. Semantic HTML
Always prefer semantic HTML elements over generic divs or spans.
❌ BAD: Non-semantic button
<div onclick={handleClick} role="button" tabindex="0">Click me</div>
✅ GOOD: Semantic HTML element
<button onclick={handleClick}>Click me</button>
6.2. ARIA Attributes
Use ARIA attributes when semantic HTML isn't sufficient, but only when necessary.
<label for="username">Username</label>
<input id="username" type="text" aria-describedby="username-hint" />
<p id="username-hint">Your username must be unique.</p>
7. Testing Approaches
Implement a robust testing strategy for Svelte applications.
7.1. Unit Testing with Vitest and Svelte Testing Library
Use vitest for your test runner and @testing-library/svelte for component testing.
// src/lib/components/Counter.test.ts
import { render, screen } from '@testing-library/svelte';
import { expect, test } from 'vitest';
import Counter from './Counter.svelte';
test('Counter increments value on click', async () => {
render(Counter);
const button = screen.getByRole('button', { name: /Count:/i });
expect(button).toHaveTextContent('Count: 0');
await button.click();
expect(button).toHaveTextContent('Count: 1');
});
7.2. End-to-End (E2E) Testing
For critical user flows, use Playwright or Cypress.
// tests/example.spec.ts (Playwright)
import { test, expect } from '@playwright/test';
test('homepage has title and intro text', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveTitle(/SvelteKit/);
await expect(page.locator('h1')).toHaveText('Welcome to SvelteKit');
});