Sveltekit Svelte5

SvelteKit + Svelte 5 Skill

Outcome

Produce production-ready SvelteKit code that is:

• Aligned with canonical types in src/lib/components/app/types.ts
• Written with Svelte 5 runes and .svelte.ts reactive hooks where appropriate
• Consistent with layout-level UI tokens, desktop-first density, and dark glassy surfaces
• Free of type errors and warnings (bun run check passes clean)
• Safe in Tauri contexts: all plugin APIs lazy-loaded and fallback-guarded

When to Use

Use this skill when tasks include:

• Implementing or migrating features in +page.svelte, +layout.svelte, or shared components
• Splitting large Svelte components into smaller, typed, composable units
• Moving state ownership between route, layout, or shared hook layers
• Debugging runtime issues (unhandled promise rejections, stale state, broken reactivity)
• Fixing type drift after domain model changes in types.ts
• Hardening Tauri plugin calls against non-Tauri or early-load failures
• Improving debug tooling pages (/debug) without breaking app conventions

Project Guardrails

These rules are non-negotiable. Violating any of them is a bug, not a style choice.

• Canonical types: src/lib/components/app/types.ts is the single source of truth. Never introduce parallel local types for domain objects.
• Field naming: Use snake_case for all domain fields (board_id, created_at, updated_at). Never camelCase domain fields.
• Status values: Must be exactly todo | in_progress | done. Never in-progress, InProgress, or any variant.
• Runes over stores: Prefer $state, $derived, $effect over legacy writable/readable Svelte stores for app state.
• Side effects belong in hooks: Keep repositories, API calls, and plugin interactions out of presentational components.
• Toolbar at layout level: The toolbar must be mounted in the layout, never duplicated at route level.
• No top-level plugin awaits: Never call Tauri plugin APIs at module load time — lazy-load inside functions or effects.

Procedure

1. Gather Context

• Read all files involved: the target route/component, its parent layout, any hooks it imports, and types.ts.
• Identify failure mode: compile-time error, runtime exception, or behavioral regression.
• Reproduce failures before touching code — use bun run check for type errors and browser/Tauri logs for runtime issues.

2. Align Types

• Diff current code against types.ts. List every field or type that has drifted.
• Update all usages consistently: component props, hook signatures, server load return shapes, API call payloads.
• Remove all local re-declarations of canonical types.
• After updates, re-run bun run check to confirm alignment before proceeding.

3. Design State Ownership

• Ask: is this state needed by more than one route or by the layout?
  • Yes → place in a shared .svelte.ts hook using $state at module scope.
  • No → keep it route-local with $state inside the component.
• Use getter functions as hook inputs when values can change (e.g., () => workspacePath not workspacePath).
• Never capture workspace path, active IDs, or user-derived values at initialization time.
• Derived values (filtered lists, computed labels) belong in $derived, not re-computed in effects.

4. Implement UI in Composable Units

• If a component exceeds ~200 lines or mixes behavior with presentation, split it.
• Parent/hook owns: data fetching, mutations, state, event handlers.
• Child components own: rendering, local interaction, emitting typed events via $props().
• Type all props explicitly — no implicit any from $$props or untyped destructuring.
• Preserve keyboard accessibility for all primary actions (buttons, form submissions, navigation).

5. Harden Async and Plugin Behavior

• Wrap all $effect bodies that contain async calls in try/catch. Surface errors to UI state, not just console.
• Lazy-import Tauri plugin APIs inside the function or effect that uses them:

  // Good
  $effect(() => {
    (async () => {
      try {
        const { readDir } = await import('@tauri-apps/plugin-fs');
        files = await readDir(path);
      } catch (e) {
        error = String(e);
      }
    })();
  });
  
  // Bad — fails at module load outside Tauri
  import { readDir } from '@tauri-apps/plugin-fs';

• Provide meaningful fallback state when plugin calls are unavailable (empty list, error message, disabled UI).

6. Apply Style Consistency

• Import tokens only from src/routes/layout.css — do not hardcode color or spacing values.
• Use compact desktop density: tight padding, small font sizes, subtle 1px borders.
• Prefer existing shadcn-svelte primitives (Button, Input, Badge, etc.) before writing custom elements.
• Dark glassy surfaces: use established background/blur token classes, not arbitrary Tailwind values.