AGENT SKILL

sveltekit-and-svelte5-runes

Complete architecture patterns, state management with Svelte 5 Runes ($state, $derived, $effect, $props), SvelteKit SSR/streaming pipelines, form actions, and production anti-patterns.

License 许可
MIT
最近更新
2026-10-17
Stars
★ 8
Forks
1

01 前言 Front Matter

name
sveltekit-and-svelte5-runes
description
Complete architecture patterns, state management with Svelte 5 Runes ($state, $derived, $effect, $props), SvelteKit SSR/streaming pipelines, form actions, and production anti-patterns.

03 SKILL.md 正文

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()

Example 2: SvelteKit Streaming Load Function & Page Component

Location: src/routes/dashboard/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

async function fetchFastMetrics(userId: string) {
  // Simulating fast DB query (50ms)
  return { userStatus: 'active', notificationsCount: 4 }
}

async function fetchSlowAnalytics(userId: string) {
  // Simulating heavy analytical query (1500ms)
  await new Promise((resolve) => setTimeout(resolve, 1500))
  return {
    monthlyRevenue: 14250.0,
    activeSubscriptions: 342,
    chartData: [10, 25, 45, 80, 120]
  }
}

export const load: PageServerLoad = async ({ locals, parent }) => {
  const session = await locals.getSession()
  if (!session?.user) {
    throw error(401, 'Unauthorized access to dashboard metrics')
  }

  // Await fast critical data for immediate initial SSR HTML response
  const fastMetrics = await fetchFastMetrics(session.user.id)

  // DO NOT await slow analytical data — return promised stream
  const slowAnalyticsPromise = fetchSlowAnalytics(session.user.id)

  return {
    user: session.user,
    fastMetrics,
    // Streamed promise payload
    streamed: {
      analytics: slowAnalyticsPromise
    }
  }
}

Location: src/routes/dashboard/+page.svelte

<script lang="ts">
  import type { PageData } from './$types'

  // Component props in Svelte 5 using $props rune
  let { data }: { data: PageData } = $props()

  // Destructure reactive references
  let fastMetrics = $derived(data.fastMetrics)
</script>

<div class="dashboard">
  <h1>Welcome, {data.user.name}</h1>

  <!-- Instant SSR Content -->
  <section class="summary-cards">
    <div class="card">Status: {fastMetrics.userStatus}</div>
    <div class="card">Unread Notifications: {fastMetrics.notificationsCount}</div>
  </section>

  <!-- Streamed Content with Promise Resolution -->
  <section class="analytics-section">
    <h2>Analytics Overview</h2>

    {#await data.streamed.analytics}
      <div class="loading-skeleton">
        <p>Loading deep analytics metrics...</p>
      </div>
    {:then analytics}
      <div class="analytics-content">
        <p>Monthly Revenue: ${analytics.monthlyRevenue.toLocaleString()}</p>
        <p>Active Subscriptions: {analytics.activeSubscriptions}</p>
      </div>
    {:catch err}
      <div class="error-box">
        <p>Failed to load analytics: {err.message}</p>
      </div>
    {/await}
  </section>
</div>

Example 3: Progressive Form Action with Action Directive

Location: src/routes/contact/+page.server.ts

import { fail, type Actions } from '@sveltejs/kit'

export const actions: Actions = {
  submitForm: async ({ request }) => {
    const formData = await request.formData()
    const email = formData.get('email')?.toString()
    const message = formData.get('message')?.toString()

    if (!email || !email.includes('@')) {
      return fail(400, { email, message, error: 'Invalid email address' })
    }

    if (!message || message.length < 10) {
      return fail(400, { email, message, error: 'Message must be at least 10 characters long' })
    }

    // Process submission...
    return { success: true, messageId: 'msg_98127391' }
  }
}

Location: src/routes/contact/+page.svelte

<script lang="ts">
  import { enhance } from '$app/forms'
  import type { ActionData } from './$types'

  let { form }: { form: ActionData } = $props()

  let isSubmitting = $state(false)
</script>

<form
  method="POST"
  action="?/submitForm"
  use:enhance={() => {
    isSubmitting = true
    return async ({ update }) => {
      isSubmitting = false
      await update()
    }
  }}
>
  <label>
    Email Address:
    <input type="email" name="email" value={form?.email ?? ''} required />
  </label>

  <label>
    Your Message:
    <textarea name="message" required>{form?.message ?? ''}</textarea>
  </label>

  {#if form?.error}
    <p class="error-msg">{form.error}</p>
  {/if}

  {#if form?.success}
    <p class="success-msg">Message sent successfully! Ref: {form.messageId}</p>
  {/if}

  <button type="submit" disabled={isSubmitting}>
    {isSubmitting ? 'Sending...' : 'Send Message'}
  </button>
</form>

Anti-Patterns & Common Pitfalls

❌ Anti-Pattern 1: Mutating Derived State or Using $effect for Computed Values

<script lang="ts">
  let count = $state(0)
  let double = $state(0)

  // BAD: Synchronizing derived state using $effect creates extra render ticks & bugs
  $effect(() => {
    double = count * 2
  })

  // GOOD: Use $derived primitive for computational projections
  let doubleDerived = $derived(count * 2)
</script>

❌ Anti-Pattern 2: Top-Level Request State Leaks in SvelteKit SSR

// BAD: Module-scoped state variable in +page.server.ts or server module
// Location: src/lib/server/userState.ts
export let currentUser: User | null = null // SHARED ACROSS REQUESTS IN NODE.JS SSR MEMORY!

export const load = async ({ locals }) => {
  currentUser = locals.user // BUG: Request A overwrites Request B's user!
}

// GOOD: Keep request-bound data strictly inside event locals or pass via return values
export const load = async ({ locals }) => {
  return { user: locals.user }
}

❌ Anti-Pattern 3: Mixing Legacy Svelte 4 Store Syntax with Runes Mode

<script lang="ts">
  import { writable } from 'svelte/store'
  
  // AVOID: Mixing old writable store with Svelte 5 runes creates unnecessary complexity
  const countStore = writable(0)

  // GOOD: Native Svelte 5 $state
  let count = $state(0)
</script>

04 同仓库更多 Skills

hamzabellouch
hamzabellouch/agent-skills

security-audit

Comprehensive security guidance, source code audit, vulnerability assessment, and penetration test review for codebases, APIs, microservices, CLI tools, libraries, and LLM-backed applications. Triggers on requests to audit a codebase, conduct security reviews, find vulnerabilities or flaws, pen-test source code, or when the user asks in Arabic (فحص أمني، تدقيق الكود أمنياً، مراجعة الثغرات، فحص أمان المشروع). Supports Guidance mode (focused review) and Full Audit mode (deterministic 6-phase harness).

★ 8
hamzabellouch
hamzabellouch/agent-skills

malware-analysis-reversing

Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.

★ 8
hamzabellouch
hamzabellouch/agent-skills

application-security-pentesting

Production Application Security (AppSec) standards, OWASP Top 10 vulnerability remediation, SAST/DAST pipeline integration, secure code review, threat modeling, and defensive security posture.

★ 8
hamzabellouch
hamzabellouch/agent-skills

oauth2-oidc-security-flows

Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.

★ 8
hamzabellouch
hamzabellouch/agent-skills

jwt-session-management-hardening

Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session revocation, or hardening API authentication.

★ 8
hamzabellouch
hamzabellouch/agent-skills

soc2-compliance-automation

Best practices for implementing SOC 2 Type II compliance controls, continuous evidence collection, infrastructure policy-as-code, and automated security monitoring. Use when automating Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy), audit logging, IAM least privilege, or CI/CD security gates.

★ 8