Svelte Optimizer

Audit a Svelte/SvelteKit codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Svelte's compiler gives fine-grained updates for free, so the wins are usually data loading, rendering mode, bundle shape and asset delivery; runes/effects and load semantics change behavior, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json with @sveltejs/kit and/or svelte). Record: SvelteKit major (3.1 current, 2.x legacy), Svelte major (5 runes, 4 legacy), adapter, Vite/vite-plugin-svelte versions, Node runtime, TypeScript, rendering mode (SSR/prerender/SPA), and whether remote functions are enabled (experimental).
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, vite.config.*, src/routes, src/hooks.*, src/env.* and .svelte/.ts sources for legacy stores/config, load waterfalls, secrets in universal load, effect fetching, SSR/build mismatches, XSS and bundle risks, with file:line evidence. Use --json to post-process.
• Classify the pain: slow first load (SSR/bundle/assets), slow navigation (load/preload), slow mutations (form actions/endpoints), hydration/CLS, deploy cold start, or code health/migration. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (production build, preview, Lighthouse, network, svelte-check).

2. Audit

The script finds cheap leads; you find the rest by reading. Read package.json, vite.config.*, src/app.html, src/routes/+layout.*, the 3-5 routes the user cares about, and their load/action/endpoint files. Load only what applies:

Measure, never guess. Run vite build and the production preview (vite preview or the adapter's server), then measure that. Dev mode and HMR are not evidence. Check per-route JS, load timing, SSR HTML/TTFB, hydration warnings and LCP/CLS.

Mark each finding Confirmed (build output, network/profiler, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as SVELTE_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- move effect/onMount fetching into load, parallelize independent awaits, add depends, fix keyed each, preload links, prerender static routes, preload the LCP image/font, lazy-load heavy widgets. Low risk.
2. Structural -- choose server vs universal load, stream non-critical data, batch N+1 queries, add form actions with use:enhance, move secrets into server-only modules, restructure layouts to avoid duplicate loads, adopt $derived instead of sync effects. Name each behavior change.
3. Heavy -- SvelteKit 2 to 3 (config into Vite, #lib, $app/state, adapters), Svelte 4 to 5 runes migration, adapter/SPA/prerender change, remote functions (experimental). Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: svelte-check, lint, tests, vite build. A break must trace to one change. Do not mix a SvelteKit/Svelte major upgrade with optimization edits. If an approved change moves data/secret handling across the server/client boundary, changes SSG/SSR output, or alters a form action, stop and ask.

6. Verify and wrap up

Re-measure the same routes and scenario: route JS, SSR TTFB/HTML, load duration, navigation requests/time, LCP/INP/CLS, and form-action latency. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Load is the data boundary. onMount/$effect fetching causes waterfalls and empty SSR HTML; use +page.ts/+page.server.ts.
• Server load for secrets, universal load for shareable data. Universal load runs in the browser; process.env/DB clients belong in +page.server.ts, hooks, or src/lib/server.
• Runes replace sync, not logic. $derived for computed values; $effect only for external side effects. An effect that writes state is usually a derived value.
• Prerender what can be static. SvelteKit makes static output fast; SPA mode adds round trips before the first pixel.
• Preload is already there; use it. SvelteKit preloads code and data on link intent by default in new apps; verify it is not disabled and that slow data is streamed.
• Bundle less. Dynamic-import heavy widgets, per-icon imports, and avoid shipping server-only/admin code to the browser.
• Caching is correctness first. Never cache per-user load data in a shared layer; state the freshness and invalidation rule.
• Docs move. SvelteKit 3 (Oct 2026) moved config into Vite, removed $app/stores and $lib; Svelte 4 runes advice is stale. Check the installed versions.