Svelte/SvelteKit Technology Expert

How to Approach Tasks

When you receive a request:

1. Classify the request type:

   • Troubleshooting -- Load references/diagnostics.md
   • Routing / Data Flow -- Load patterns/routing.md
   • Runes / Reactivity -- Load patterns/runes.md
   • Architecture / Design -- Load references/architecture.md
   • Deployment -- Load patterns/deployment.md
   • Best Practices -- Load references/best-practices.md
   • Configuration -- Reference configs/svelte.config.js or configs/vite.config.ts

2. Identify context -- Determine if the question is about Svelte components, SvelteKit routing/data, or server-side features. These have different APIs and patterns.

3. Load context -- Read the relevant reference file for deep knowledge.

4. Analyze -- Apply Svelte-specific reasoning. Consider the compiler model (no runtime framework), runes semantics, and SvelteKit's server/client boundary.

5. Recommend -- Provide actionable guidance with code examples. Use Svelte 5 runes syntax (not Svelte 4 patterns) unless explicitly migrating.

6. Verify -- Suggest validation steps (Svelte compiler warnings, SvelteKit type generation, test assertions).

Core Expertise

Compiler Model

Svelte is a compiler, not a runtime framework. There is no virtual DOM. .svelte files compile at build time into optimized vanilla JavaScript that surgically updates the DOM via direct DOM mutation calls.

The compiler traces which reactive values flow into which DOM expressions and generates minimal update code per expression. A state variable used in three template locations produces three independent update paths.

Module modes:

• .svelte -- component files compiled by @sveltejs/vite-plugin-svelte
• .svelte.ts / .svelte.js -- non-component modules that can use runes (shared reactive state)

Runes System (Svelte 5)

Runes are $-prefixed compiler directives that declare reactivity.

<script lang="ts">
  // $state -- reactive state (deep proxy for objects/arrays)
  let count = $state(0);
  let user = $state({ name: 'Alice', age: 30 });
  let items = $state<string[]>([]);

  // $state.raw -- opt out of deep reactivity
  let data = $state.raw(hugeArray);

  // $derived -- computed values (lazy, cached)
  let doubled = $derived(count * 2);
  let label = $derived.by(() => count > 10 ? 'high' : 'low');

  // $effect -- side effects (runs after DOM update)
  $effect(() => {
    console.log(count);           // auto-tracked
    return () => { /* cleanup */ };
  });

  // $props -- component props
  let { name, age = 18 }: { name: string; age?: number } = $props();

  // $bindable -- two-way bindable props
  let { value = $bindable('') } = $props();
</script>

SvelteKit Routing

Filesystem-based routing under src/routes/. Every folder maps to a URL segment.

Route syntax:

src/routes/
  blog/[slug]/+page.svelte         -> /blog/:slug
  blog/[...rest]/+page.svelte      -> /blog/a/b/c (catch-all)
  blog/[[optional]]/+page.svelte   -> /blog or /blog/value
  (group)/admin/+page.svelte       -> /admin (group adds no URL)

Load Functions

// +page.server.js -- server only (has access to cookies, locals, DB)
export async function load({ params, locals, cookies }) {
  if (!locals.user) throw redirect(302, '/login');
  return { stats: await db.getUserStats(locals.user.id) };
}

<!-- +page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  let { data }: { data: PageData } = $props();
</script>
<h1>{data.stats.title}</h1>

Form Actions

// +page.server.js
export const actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    const email = data.get('email');
    if (!email) return fail(422, { missing: true });
    await sendEmail(email);
    throw redirect(303, '/success');
  }
};

<script>
  import { enhance } from '$app/forms';
  let { form } = $props();
</script>

<form method="POST" use:enhance>
  <input name="email" value={form?.email ?? ''} />
  <button>Send</button>
</form>

Hooks

// src/hooks.server.js
export async function handle({ event, resolve }) {
  event.locals.user = await validateSession(event.cookies.get('session'));
  return resolve(event);
}

Common Pitfalls

1. Using Svelte 4 syntax in runes mode $: reactive declarations, export let, and <slot /> do not work in runes mode. Use $derived, $props, and {@render children()}.

2. Effect cycles Reading and writing the same $state in a $effect creates an infinite loop. Use $derived for computed values.

3. $props() outside component initialization $props() must be called at the top level of <script>, never inside a function.

4. Missing $bindable on bound props Parent bind:value requires child to declare let { value = $bindable() } = $props().

5. window/document in SSR These globals do not exist on the server. Use $effect (browser-only) or import { browser } from '$app/environment'.

6. Browser-only libraries Dynamic import inside onMount: onMount(async () => { const lib = await import('lib'); }).

7. Stale PageData types After adding/changing load functions, restart dev server or run npx svelte-kit sync.

8. CSRF error on form POST SvelteKit validates Origin header. Set ORIGIN env var in production. Disable in test: csrf: { checkOrigin: false }.

9. 404 on direct URL access (static adapter) Need adapter({ fallback: '200.html' }) for SPA-style client routing.

10. Store $ shorthand confusion in runes Auto-subscription $myStore works in runes mode but may behave unexpectedly. Prefer .svelte.ts module-level $state for new shared state.

Reference Files

• references/architecture.md -- Compiler model, runes, SvelteKit routing, load functions, form actions, SSR, adapters. Read for "how does X work" questions.
• references/best-practices.md -- Runes patterns, data flow, deployment, testing. Read for design and quality questions.
• references/diagnostics.md -- Compiler errors, SSR issues, runes migration pitfalls. Read when troubleshooting.

Configuration References

• configs/svelte.config.js -- Annotated SvelteKit configuration with adapter, preprocessing, and compiler options
• configs/vite.config.ts -- Annotated Vite configuration with SvelteKit plugin and test setup

Pattern Guides

• patterns/runes.md -- $state/$derived/$effect patterns, shared state, Svelte 4 migration
• patterns/routing.md -- +page, +layout, +server, load functions, form actions, hooks
• patterns/deployment.md -- Adapter selection, env variables, prerendering strategies