sveltekit-and-svelte5-runes

SvelteKit & Svelte 5 Runes Architecture Guide

Core Architectural Principles

1. Svelte 5 Runes Paradigm

• Fine-Grained Signals: Svelte 5 replaces stores (writable, readable) and compiler-magic $: declarations with deep reactive primitives (Runes).
• Primitives:
  • $state(initial): Deeply reactive state definition. Use $state.raw(initial) for non-reactive large structures (e.g., WebGL objects, large immutable arrays).
  • $derived(expression): Pure, memoized computational projections. Use $derived.by(() => { ... }) for complex multi-statement computations.
  • $effect(() => { ... }): Side-effect execution (DOM mutation, external sync). Must remain free of state mutations to prevent feedback loops.
  • $props(): Component property declaration with TS interface support and default assignments.
  • $bindable(): Explicit opt-in two-way data binding for props.
• Class-Based Reactive Stores: Encapsulate domain logic inside standard ES classes utilizing $state and $derived properties, completely eliminating legacy store boilerplate.

2. SvelteKit Data Flow & SSR Isolation

• Universal vs Server Load:
  • Use +page.server.ts for database access, secret keys, or direct server APIs.
  • Use +page.ts for universal client/server fetching or rendering logic.
• Streaming Async Data: Return non-awaited promises in +page.server.ts to stream slow data dependencies using SvelteKit's built-in streaming support.
• Form Actions & Progressive Enhancement: Always leverage SvelteKit Form Actions with use:enhance to ensure forms work seamlessly with or without JavaScript enabled.

---

Production Code Examples

Example 1: Svelte 5 Class-Based Reactive State Store

Location: src/lib/stores/cart.svelte.ts

export interface CartItem {
  id: string
  name: string
  price: number
  quantity: number
}

export class ShoppingCartStore {
  // Deeply reactive state array
  items = $state<CartItem[]>([])
  discountCode = $state<string | null>(null)
  discountPercent = $state<number>(0)

  // Derived memoized values
  itemCount = $derived(this.items.reduce((total, item) => total + item.quantity, 0))
  
  subtotal = $derived(
    this.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
  )

  tax = $derived.by(() => {
    const taxableAmount = Math.max(0, this.subtotal * (1 - this.discountPercent))
    return taxableAmount * 0.08 // 8% sales tax
  })

  total = $derived(Math.max(0, this.subtotal * (1 - this.discountPercent)) + this.tax)

  addItem(newItem: Omit<CartItem, 'quantity'>) {
    const existing = this.items.find(i => i.id === newItem.id)
    if (existing) {
      existing.quantity += 1
    } else {
      this.items.push({ ...newItem, quantity: 1 })
    }
  }

  removeItem(id: string) {
    this.items = this.items.filter(i => i.id !== id)
  }

  updateQuantity(id: string, quantity: number) {
    const item = this.items.find(i => i.id === id)
    if (item) {
      if (quantity <= 0) {
        this.removeItem(id)
      } else {
        item.quantity = quantity
      }
    }
  }

  applyDiscount(code: string, percent: number) {
    this.discountCode = code
    this.discountPercent = percent / 100
  }

  clear() {
    this.items = []
    this.discountCode = null
    this.discountPercent = 0
  }
}

// Global or scoped instantiations
export const cartStore = new ShoppingCartStore()