roninforge-sveltekit

Cursor plugin for SvelteKit 2 + Svelte 5 (Runes) + TypeScript. Pinned to svelte ^5.55.7 and @sveltejs/kit ^2.60.1. Teaches the Svelte 5 runes that LLMs trained pre-October 2024 do not know ($state, $derived, $props, $bindable, $effect, $props.id()), the snippets-replace-slots model, callback props that replace createEventDispatcher, the .svelte.ts state module pattern that replaces writable() stores, the SvelteKit 2 no-throw error() / redirect() API, mandatory cookies path, and the $app/state replacement for $app/stores in 2.12+. Catches 40 LLM regressions with BAD / GOOD TypeScript + Svelte pairs.

The Problem

LLMs trained on Svelte 4 / SvelteKit 1 emit code that does not match a fresh Svelte 5 + SvelteKit 2 install. They write:

• let count = 0 for component state without $state(0) (silently non-reactive in runes mode)
• $: doubled = count * 2 in runes-mode files (syntax error)
• export let prop in any file using runes (compile error)
• <button on:click={fn}> with the on: namespace (removed in Svelte 5)
• Event modifiers |preventDefault, |stopPropagation, |self, |once (removed)
• createEventDispatcher + dispatch('foo', payload) (replaced by callback props)
• <slot /> and <slot name="x" /> (replaced by snippets and {@render children?.()})
• new App({ target }) for the client root or for tests (Svelte 5 dropped the class instance API; use mount() or render())
• bind:this={el} to a non-$state variable (assignment is invisible to consumers)
• Destructuring a $state proxy and reading the destructured local (loses reactivity)
• $effect used to derive a value (use $derived)
• $effect that reads and writes the same state (infinite loop; wrap in untrack)
• $state for arrays larger than 1000 elements without considering $state.raw
• $effect used to initialise state on the server (effects only run in the browser)
• Reading state inside $effect after await (no longer tracked)
• throw error(...) / throw redirect(...) in SvelteKit 2 (helpers throw internally; just call them)
• Wrapping redirect() in try/catch without isRedirect re-throw (silently swallowed)
• cookies.set / cookies.delete without explicit path: '/' (throws in SvelteKit 2)
• Top-level unawaited promises in load (SvelteKit 2 stopped auto-awaiting; use Promise.all)
• goto('https://external') (rejected in SvelteKit 2; use window.location.href)
• $page from $app/stores in new code (use page from $app/state, 2.12+)
• resolvePath (renamed resolveRoute in $app/paths)
• use:enhance callback args form / data (renamed formElement / formData in v2)
• File-input forms missing enctype="multipart/form-data" (throws under enhance)
• $env/dynamic/* read inside a prerendered route (use $env/static/*)
• writable() / readable() stores for component-local state (use $state)
• Stores in plain .ts modules for shared cross-component state (use .svelte.ts with a class)
• lucide-svelte import (use @lucide/svelte, the scoped Svelte 5 fork)
• @melt-ui/svelte in new Svelte 5 code (use bits-ui, the documented headless layer)
• Felte forms (felte + @felte/validator-zod) effectively abandoned for SvelteKit (use sveltekit-superforms + formsnap + zod)
• <img> for above-the-fold images (use <enhanced:img> from @sveltejs/enhanced-img)
• CustomEvent<T> typed payloads in handlers (callback props pass plain function args)
• withDefaults-style prop defaults (Svelte 5 supports defaults inline in $props() destructure)
• Manually generating SSR-safe IDs for ARIA (use $props.id() in 5.20+)
• <slot> rendered alongside let { children } = $props() (the two systems do not co-exist)
• Mutating non-$bindable props in the child (throws in dev)
• +page.ts exports without satisfies PageLoad (loses generated-type propagation)
• mount(App) in tests without unmount() (handlers leak across tests; use @testing-library/svelte)

Why this plugin (vs the existing community Svelte / SvelteKit rules)

A handful of Svelte and SvelteKit rules already live on cursor.directory: svelte.mdc, sveltekit.mdc, svelte-tailwind.mdc, and a few mixed-stack files. They are shallow and have three structural problems this plugin fixes:

1. They pin nothing or pin pre-Svelte-5 / pre-Kit-2. Across all of them, zero mentions of $state, $derived, $props, $bindable, $effect, $props.id(), snippets, callback-prop event handling, .svelte.ts state modules, mount() / hydrate(), the SvelteKit 2 no-throw error() / redirect(), mandatory cookies.path, top-level Promise.all in load, $app/state, or the formElement / formData rename in use:enhance. Svelte 5 (October 2024) and SvelteKit 2 (December 2023, with $app/state in 2.12) post-date all of them. This plugin pins svelte ^5.55.7 and @sveltejs/kit ^2.60.1 explicitly.

2. Most still teach on:click / <slot> / createEventDispatcher / export let / writable() for component state. All five are deprecated or compile errors in Svelte 5 runes mode. They also teach $page from $app/stores (deprecated 2.12+) and throw redirect(...) (broken in v2).

3. They ship flat .cursorrules text without globs, fixtures, skills, or an agent. This plugin ships:

   • 10 MDC rules with proper globs so the routes check fires on src/routes/**, the runes check on **/*.svelte + **/*.svelte.ts, the testing check on **/*.test.ts, etc.
   • 40 documented anti-patterns with BAD / GOOD TypeScript + Svelte pairs (the existing rules have zero)
   • 5 skills: /svelte-new-component, /sveltekit-new-route, /sveltekit-new-form-action, /sveltekit-migrate-to-runes, /sveltekit-validate
   • 1 reviewer agent with severity grouping (CRITICAL / ERROR / WARN / NIT) and per-file checks
   • 2 fixture projects: correct-sample (gold-standard SvelteKit 2.60.1 + Svelte 5.55.7 + bits-ui + sveltekit-superforms + formsnap + zod) and anti-pattern-sample (every file violates at least one tracked anti-pattern, pinned to svelte ^4.2.0 + @sveltejs/kit ^1.27.0 + lucide-svelte ^0.300.0 to demonstrate the Svelte 4 / Kit 1 hangover)

Install

Copy the rules, skills, and agent into your project's Cursor configuration. Back up your existing files first; cp -r will overwrite same-named rules.

git clone https://github.com/RoninForge/roninforge-sveltekit.git

# Use -n to avoid clobbering an existing customised rule of the same name.
cp -rn roninforge-sveltekit/rules/*  your-project/.cursor/rules/
cp -rn roninforge-sveltekit/skills/* your-project/.cursor/skills/
cp -rn roninforge-sveltekit/agents/* your-project/.cursor/agents/

Or vendor the whole repo as a git submodule under your-project/.cursor/plugins/. Refer to the Cursor plugin docs for the current global-install path on your Cursor version.

What's Included

Rules (10 files)

Skills (5 commands)

Agent (1 subagent)

Fixtures

tests/fixtures/correct-sample/ is a slim SvelteKit 2.60.1 + Svelte 5.55.7 + bits-ui + sveltekit-superforms + formsnap + zod project demonstrating the gold-standard shape: runes everywhere, callback props, snippets, .svelte.ts state module, page from $app/state, error() / redirect() without throw, cookies with path, satisfies PageLoad / Actions, superforms-wired login, reroute hook.

tests/fixtures/anti-pattern-sample/ is the inverse. Every file violates a numbered anti-pattern. package.json pins svelte ^4.2.0 + @sveltejs/kit ^1.27.0 + lucide-svelte ^0.300.0 + vitest ^0.34.0 on purpose - the Svelte 4 / Kit 1 era is the LLM-training dataset for most pre-2025 models. Tracked violations: #2 ($:), #3 (export let), #4 (on:click), #5 (event modifiers), #6 (createEventDispatcher), #7 (<slot>), #17 (throw redirect / throw error), #19 (cookies without path), #20 (top-level unawaited load), #22 ($page from $app/stores), #28 (writable for component-local), #29 (.ts shared store), #30 (lucide-svelte).

Versioning

Rules target svelte ^5.55.7 on @sveltejs/kit ^2.60.1 with Node 24 LTS. Most patterns work back to Svelte 5.0 / Kit 2.0 with the deltas called out inline. Where the rule cites a version ($props.id() 5.20+, $app/state Kit 2.12+, reroute hook Kit 2.3+, paths.relative default flip Kit 2.0, cookies.path mandatory Kit 2.0, error() / redirect() no-throw Kit 2.0), verify against the changelog for the version you have installed before adopting.

License

MIT - see LICENSE

Links

• Svelte 5 release notes
• SvelteKit 2 migration guide
• Runes overview
• bits-ui
• sveltekit-superforms
• Cursor Plugin Documentation
• RoninForge