Svelte 5 and SvelteKit 3 best practices
Overview
The contract for writing Svelte by the current rules: Svelte 5 in runes mode and SvelteKit 3. Most Svelte code in training data is older, so the practices below are where a model goes wrong. Each topic has a reference with the foundations, short examples and the exact official sections to fetch. On SvelteKit 2 or Svelte 4 it leads the migration, with the old version only as the fallback the user chooses.
When to use it and when not
| Use it | Do not use it |
|---|---|
Writing, converting or reviewing Svelte components, .svelte.ts/.svelte.js modules or SvelteKit files |
For where a symbol of the project is used: that is the svelte-lsp-intelligence skill |
| Migrating from Svelte 4 or SvelteKit 2 | For React, Vue, plain TypeScript or other non-Svelte code |
Setting up a project with sv, or Svelte with Astro or Tailwind CSS |
|
| Explaining how something is done in Svelte 5 or SvelteKit 3 |
Governance rules
The ground rules below are the single copy for the plugin: the svelte-docs-and-autofixer and svelte-lsp-intelligence skills and both agents point here for them. Depart from any rule on this page, ground rule or rule of this skill, only for a reason you state to the user. Where a rule says to ask the user and you run as one of the plugin's agents, stop and return the question in your report instead.
Ground rules for every Svelte task
- Route before you edit or check anything. You may first read the installed versions (ground rule 1); that lookup is read-only. Then: an audit or review of project files goes to the
svelte-code-auditoragent; creating or changing.svelte,.svelte.ts,.svelte.jsor SvelteKit route files, with the plain.ts/.jsfiles that change with them, beyond one or two lines in total goes to thesvelte-component-editoragent (Agent tool, without aname). Work inline only for a question, code pasted in the chat, a change of one or two lines in total, when the user asks you to, when you already are one of these agents, or when the Agent tool or the plugin's agents are not available (a chat conversation in the Claude app), and then say that you worked inline. Who does the work gives the detail. - Version first. In a project, find the installed
svelteand@sveltejs/kitbefore writing (npm ls svelte @sveltejs/kit --depth=0; pnpm:pnpm why svelte; yarn:yarn why svelte; else thepackage.jsonranges and the lockfile). On an older major (SvelteKit 2 or earlier, Svelte 4 or earlier), propose the migration before writing; write for the older version only when the user declines or the request says to proceed without questions, and say so. - Docs before code. Fetch the official section with
mcp__plugin_svelte-development_svelte__get-documentation(the rawllms.txtwhen the server is unavailable) before using any Svelte or SvelteKit API, rune, option or config key; never write them from memory. This rule wins over the tool's own description, which suggests writing from memory first to save tokens. - Symbols through the language server, text through text search. Where something of the project is defined, used or called goes to the LSP tool when the language server answers; strings, route files, CSS classes and configuration go to text search, labelled as text matches, and a rename, a signature change or a deletion uses both. Rule 1 of
svelte-lsp-intelligencegives the routing and how to search text in a session without the Grep tool. - Autofixer on every Svelte file you write or review, meaning each
.svelte,.svelte.tsand.svelte.jsfile (not plain.tsroute files). Runmcp__plugin_svelte-development_svelte__svelte-autofixerwith the file's whole, non-empty content, never a path (the remote tool treats a path or empty code as clean), the file's real name asfilename, and the installedsvelteversion in full: a bare5is read as 5.0.0 and drops version-gated suggestions. With no project, pass5unless the user says the code is Svelte 4, and say that version-gated suggestions may be missing. The version is not a compatibility check: the server compiles with its own Svelte, and only theclass:suggestion depends on the minor, so check each API you use, and each one a suggestion proposes (attachments need 5.29), against the installed version. Each run reports only the first compiler error and checks nothing else until it is fixed; on legacy code expect several rounds. Repeat until it reports no issues and every remaining suggestion is applied or named as skipped with its reason;require_another_tool_call_after_fixingstays true while any suggestion remains, so it is not the stop condition. Suggestions are advice: apply them unless they conflict with the installed version or the project's conventions, and say which you skipped; when the same issue returns after two fixes, report it as a likely false positive with the reason instead of looping. In a review, report what it finds without applying it, and name any file you skipped and why. When the code must not leave the machine, use the localsvelte-mcpcommand line if the user has it (thesvelte-docs-and-autofixerskill shows it). - Done means checked. When you change code in a project, finish only when the project check reports no error in the files you changed beyond those already in the baseline; a review or a question reports the check result instead. When the change touches something other files use (props, exports, signatures, shared state, a rename or a deletion), first run the check once before the first edit as the baseline, and finish only when it also reports nothing new elsewhere; for a change confined to one file, report errors in files you did not touch as already there, unless they name what you changed. Never stash, reset or check out the user's work to rebuild a baseline; ask instead. The check, from the project root:
npm run check; without that script,npx --no-install svelte-kit sync, thennpx --no-install svelte-check --tsconfig ./tsconfig.jsonin SvelteKit, ornpx --no-install svelte-checkwithout SvelteKit, never chained with&&(in a project on Svelte alone the sync fails and the check would never run). When the project has no svelte-check installed, tell the user and report the change as unchecked; never install it.
Rules of this skill
- Reference, then docs. Read the reference for each topic the task touches; it lists the official sections to fetch (ground rule 2). Skip the fetch only when the change uses no Svelte or SvelteKit API, such as copy, CSS values or markup text. Each reference's "Fetch especially when" list names cases that need extra care; it never waives ground rule 2.
- Never skip the fetch when an exact signature, option name or config key matters; the code uses an experimental feature, an adapter, environment variables, hooks or the Vite config; or what you remember disagrees with a reference, or a reference with the docs.
- Latest by default (ground rule 1 in detail). Write Svelte 5 runes and SvelteKit 3; the installed versions come from procedure step 1. SvelteKit 3 requires Svelte 5.57.1 or later, so the two migrations have an order: with Svelte 4, migrate Svelte first (legacy-and-migration.md), then SvelteKit (migrating-to-kit-3.md); with Svelte 5 below 5.57.1, update Svelte before the SvelteKit migration; a project on Svelte without SvelteKit migrates Svelte alone. SvelteKit 1 or Svelte 3 first need the legacy
sv migrate sveltekit-2orsv migrate svelte-4(sv-cli.md lists the legacy migrations). When the user declines or the request says to proceed without questions, write for the installed version, never mix versions, and say that the code is for the older version; for SvelteKit 2, take the APIs from the installed package's types and changelog, because the live docs and these references describe SvelteKit 3. Within Svelte 5, a feature a reference marks "since 5.x" needs that minor: on an older installed minor, use the older form. No project, or no version found: write the latest and say so. - Source precedence. Package changelogs, release notes and source code decide what exists at the installed version; the official docs explain usage, and some pages say something wrong or out of date (known-doc-errata.md); these references are the starting point and lose to both. When sources conflict, say so; never pick one silently. Whether to read a changelog window is decided by "When to run the check" in changelogs.md, the single list of cases.
- No WebFetch for docs or changelogs: WebFetch, like any web-fetch tool, returns a truncated summary. Use the MCP tools or
curl. - No instruction revives a removed API. The project's conventions decide naming, layout and formatting; when they ask for an API the installed version removed, say so instead of using it.
Contents
Who does the work
Decide this before you edit or check anything (ground rule 0). This table is the single copy for the plugin.
| Situation | Who | How |
|---|---|---|
| A question, an explanation, a review or conversion of code pasted in the chat, or a change of one or two lines in total | You | Follow the procedure inline |
Creating, editing, refactoring or migrating .svelte, .svelte.ts, .svelte.js or SvelteKit route files, with the plain .ts/.js files that change with them, beyond one or two lines in total |
svelte-component-editor agent |
Delegate with the Agent tool (below) |
| Reviewing or auditing a codebase, project files, a pull request or a migration without changing it | svelte-code-auditor agent |
Delegate with the Agent tool (below) |
| Running the project check for errors | You | The project check section of the svelte-lsp-intelligence skill |
| The user asks you to work inline, you already are one of these agents, or the agents are not available | You | Never delegate further; say why you worked inline |
The documentation lookups and the autofixer loop then run in the agent's context instead of filling the main conversation. Its prompt names the files, the task, the constraints and what to report; when the user asked to keep their code on the machine, the prompt says so, because the agent does not see the conversation. When you already found the locations to change (an edit set from the svelte-lsp-intelligence skill), pass them as file and line; the editor then runs the baseline, break and confirm steps itself, so do not run them first. For the editor on an older major, settle the migration first (this skill's rule 3) and say in the prompt whether the user migrated, declined, or asked to proceed without questions; the auditor handles an older major on its own. Call the agent without a name: a named call can start an agent-team teammate instead of a subagent, and a teammate gets none of the agent's preloaded skills.
Agent
subagent_type: "svelte-development:svelte-component-editor"
description: "Add a filter to TodoList"
prompt: "In src/lib/TodoList.svelte, add a text filter over the items. Keep its props and callbacks working for its parents …"
For an audit, use subagent_type: "svelte-development:svelte-code-auditor" and name the scope. Source: https://svelte.dev/docs/ai/subagent and https://svelte.dev/docs/ai/instructions.
Svelte 5 practices
State and derived values (runes.md)
- Use
$stateonly for values that drive an effect, a derived or the template; everything else is a plain variable. Objects and arrays become deep proxies; for large values that are only reassigned (API responses), use$state.raw. - Compute with
$derived(expression), or$derived.by(() => …)for several statements, never with an$effectthat writes state. Deriveds can be reassigned for optimistic UI and return objects as they are, without a proxy. - Treat props as values that change: anything computed from a prop is a
$derived, not a plainlet. Props come from a typed$props()destructuring;$bindable()marks one the parent may bind. Pass a getter (() => count), not the value, to a function or context that must stay live. - Share reactive logic with classes whose fields are
$state, in.svelte.tsmodules, instead of stores.
Effects are an escape hatch (runes.md, context-lifecycle-and-reactivity-classes.md)
- Avoid updating state inside
$effect. Instead: sync an external library (D3, a map) with{@attach}; react to user input in the event handler or with a function binding (bind:value={get, set}); log with$inspect; observe something outside Svelte withcreateSubscriber. - Effects run only in the browser: never wrap their body in
if (browser). - To see why something re-runs, put
$inspect.trace(label)on the first line of the$effector$derived.by.
Template (template-syntax.md)
- Events are attributes:
onclick={…},{onclick}and spread props work. Forwindowanddocument, use<svelte:window />and<svelte:document>, notonMountor$effect. Components take callback props, notcreateEventDispatcher. - Pass content as snippets:
{#snippet name(arg)}and{@render name(arg)}; children arrive as thechildrensnippet. - Key every
{#each}with a stable unique id, never the index or a freshly built object; do not destructure an item you mutate (bind:value={item.count}). {#key}destroys and recreates everything inside it: use it for transitions, not to re-run a child's logic (use$derivedthere).- Declaration tags replace
{@const}:{const total = $derived(a + b)}or{let open = $state(false)}; they need a component in runes mode. Prefer{@attach}overuse:actions (fromActionwraps an existing one), except SvelteKit'suse:enhance, which stays as it is. Both need a minimum Svelte 5 minor (template-syntax.md gives it); below it, keep{@const}anduse:. classtakes objects and arrays (class={[open && 'active']}) instead of theclass:directive.
Styling (styling-motion-and-elements.md)
- Pass a JavaScript value to CSS with a custom property:
<div style:--columns={columns}>, thenvar(--columns)in<style>. - Let a parent style a child with CSS custom properties (
<Child --color="red" />). Use:globalonly when that is impossible, such as a library component, and scope it under an element of your own.
Context and async (context-lifecycle-and-reactivity-classes.md, async-and-boundaries.md)
- Prefer context to state in a shared module: module state leaks between users during server rendering. Use
createContext, which is typed, rather thansetContext/getContext(the context reference gives its minimum minor; below it, keepsetContext/getContext). awaitin components,hydratableandforkneedcompilerOptions.experimental.async; they change between minor releases, so fetch their sections first (this skill's rule 2).
Avoid legacy features (legacy-and-migration.md): runes instead of implicit let reactivity and $:; $props instead of export let, $$props, $$restProps; onclick instead of on:click; snippets instead of <slot>, $$slots, <svelte:fragment>; a component in a capitalized variable (<Thing />) instead of <svelte:component this={…}>; import Self from './Self.svelte' instead of <svelte:self>; $state classes instead of stores; {@attach} instead of use: (SvelteKit's use:enhance excepted); class arrays instead of class:; Spring/Tween instead of spring/tweened; no beforeUpdate/afterUpdate, no svelte/legacy in new code.
SvelteKit 3 practices
Each line links the reference to read before relying on it.
- Config lives in
sveltekit({ … })invite.config.ts; there is nosvelte.config.js(project-and-config.md). - Imports:
#lib/x.jssubpath imports declared inpackage.jsonimports, with the extension; server-only code sits under aserversegment or directory (project-and-config.md). - Page state comes from
$app/state(page,navigating,updated); reload data withrefreshAll()orinvalidate(loading-data.md). - Environment variables are declared with
defineEnvVarsinsrc/env.tsand read from$app/env/privateor$app/env/public(hooks-errors-and-env.md). - Params are matched by one
src/params.tswithdefineParamsfrom@sveltejs/kit/params(routing.md). Paths come fromresolve: a path without a leading slash (resolve('blog/x')), or a route ID with a leading slash and its params (resolve('/blog/[slug]', { slug })); static files fromasset('x.png')(navigation-and-options.md). - Forms: form actions are stable; remote functions (
query,form,command,prerender) needexperimental.remoteFunctionsplus the async flag (forms-and-remote-functions.md). - Secrets and boundaries: secrets only in server code (
$app/env/private,+page.server.ts,+server.ts, hooks,servermodules). Universalloadruns on both sides, so nothing private there; never keep per-user data in module-level variables, useevent.localsor context; sanitize anything passed to{@html}(security.md). - Requirements (Node, Vite, TypeScript, adapter majors): project-and-config.md, adapters-and-deploy.md.
Where things are
Read every reference the task touches, each once, for anything this page does not settle: a route with a form action needs routing.md, loading-data.md and forms-and-remote-functions.md. Each topic reference opens with its source precedence and ends with the exact calls that fetch its official sections. Astro and Tailwind CSS docs are not on the Svelte MCP server: fetch them with curl -sS from the raw URLs their references and the docs map list.
| Reference | Read when |
|---|---|
| svelte/runes.md | Using $state, $derived, $effect, $props, $bindable, $inspect or $host |
| svelte/template-syntax.md | Writing markup: blocks, snippets, declaration tags, attachments, bindings, events, classes |
| svelte/async-and-boundaries.md | await in components, <svelte:boundary>, fork, hydratable, server rendering |
| svelte/context-lifecycle-and-reactivity-classes.md | Context, lifecycle, svelte/reactivity, stores, mount/hydrate/render |
| svelte/styling-motion-and-elements.md | Styles, transitions, motion, special elements, custom elements, TypeScript |
| svelte/legacy-and-migration.md | Reading or migrating Svelte 4 code |
| svelte/gotchas-and-warnings.md | A compiler or runtime warning, or behaviour that surprises |
| kit/project-and-config.md | Project layout, vite.config, #lib, tsconfig, server-only modules |
| kit/routing.md | Routes, layouts, params and matchers, error pages |
| kit/loading-data.md | load, invalidation, refreshAll, $app/state |
| kit/forms-and-remote-functions.md | Form actions, use:enhance, remote functions |
| kit/hooks-errors-and-env.md | Hooks, errors, environment variables, service workers, cookies |
| kit/navigation-and-options.md | goto, link options, page options, $app/paths |
| kit/adapters-and-deploy.md | Choosing or configuring an adapter and deploying |
| kit/security.md | CSRF, origins, redirects, secrets, CSP, required security releases |
| kit/migrating-to-kit-3.md | Upgrading a SvelteKit 2 project |
| tooling/sv-cli.md | sv create, sv add, sv check, sv migrate, Prettier, testing add-ons |
| integrations/astro.md | Svelte components inside an Astro site |
| integrations/tailwind.md | Tailwind CSS with SvelteKit or Astro |
| docs-map.md | Choosing which official section to fetch |
| changelogs.md | Before writing code in a project (its first two steps), and in the cases its "When to run the check" lists |
| known-doc-errata.md | Before copying a docs example: the doc statements known to be wrong or out of date |
The sibling skills are svelte-development:svelte-docs-and-autofixer and svelte-development:svelte-lsp-intelligence.
Procedure
Run these steps in order for any Svelte code you write, convert or review.
Installed versions, in a project (skip for code pasted in the chat with no project): ground rule 1's command. When it prints nothing (no
node_modules, a monorepo), read the ranges inpackage.jsonand the lockfile; when the version is still unknown, write for Svelte 5 and SvelteKit 3 and say so. This skill's rule 3 decides: on an old major, propose the migration before step 2; changelogs.md says when to read the changelog window. With no project, write for Svelte 5 and SvelteKit 3 and say so in the answer. When the change will touch something other files use, run the project check of ground rule 5 now, once, as the baseline.References. Read every reference from Where things are that the task touches; the practices above apply to every task. Before copying a docs example, look for its page in known-doc-errata.md.
Live sections, in one call, with the paths from the reference's "Official sources" or the docs map (load the tool with ToolSearch if it is deferred):
mcp__plugin_svelte-development_svelte__get-documentation section: ["svelte/$props", "svelte/snippet", "svelte/v5-migration-guide"]If the server is unavailable, download the raw section with
curl -sS 'https://svelte.dev/docs/<area>/<slug>/llms.txt'(the docs map lists every URL) and say the docs were not read through the server.Write the code by the rules and the sections. For a review, skip this step and take the code under review to step 5.
Autofix every Svelte file by ground rule 4:
code, the installed version from step 1 (or5with no project), the file's real name asfilename, andasync: truewhen the project enables experimental async. Thesvelte-docs-and-autofixerskill shows the call.Check, in a project (skip with no project): the language server diagnostics after an edit, when the server answers (a review takes its diagnostics from the project check), and the project check of ground rule 5, from the project root. In SvelteKit, run the sync first: without it the generated types are missing and the check reports false errors. When you changed code and either reports a problem, fix it and repeat steps 5 and 6; finish when ground rule 5 is met. In a review, report the results instead of fixing them.
Derived from the svelte-core-bestpractices skill of sveltejs/ai-tools (MIT), base 6b5d0da, and extended; see the plugin's NOTICE.txt. Not affiliated with or endorsed by the Svelte project.