<!--
taken from Reddit post
https://www.reddit.com/r/sveltejs/comments/1fbi97g/i_created_a_cursorrules_file_so_that_claude/
-->
I'm using svelte 5 instead of svelte 4 here is an overview of the
changes.
#### Overview
Svelte 5 introduces runes, a set of advanced primitives for
controlling reactivity. The runes replace certain non-runes features
and provide more explicit control over state and effects.
#### $state
- **Purpose:** Declare reactive state.
- **Usage:**
```svelte
<script>
let count = $state(0)
</script>
```
- **Replaces:** Top-level `let` declarations in non-runes mode.
- **Class Fields:**
```javascript
class Todo {
done = $state(false)
text = $state()
constructor(text) {
this.text = text
}
}
```
- **Deep Reactivity:** Only plain objects and arrays become deeply
reactive.
#### $state.raw
- **Purpose:** Declare state that cannot be mutated, only reassigned.
- **Usage:**
```svelte
<script>
let numbers = $state.raw([1, 2, 3])
</script>
```
- **Performance:** Improves with large arrays and objects.
#### $state.snapshot
- **Purpose:** Take a static snapshot of $state.
- **Usage:**
```svelte
<script>
let counter = $state({ count: 0 })
function onClick() {
console.log($state.snapshot(counter))
}
</script>
```
#### $derived
- **Purpose:** Declare derived state.
- **Usage:**
```svelte
<script>
let count = $state(0)
let doubled = $derived(count * 2)
</script>
```
- **Replaces:** Reactive variables computed using `$:` in non-runes
mode.
#### $derived.by
- **Purpose:** Create complex derivations with a function.
- **Usage:**
```svelte
<script>
let numbers = $state([1, 2, 3])
let total = $derived.by(() => numbers.reduce((a, b) => a + b, 0))
</script>
```
#### $effect
- **Purpose:** Run side-effects when values change.
- **Usage:**
```svelte
<script>
let size = $state(50)
let color = $state('#ff3e00')
$effect(() => {
const context = canvas.getContext('2d')
context.clearRect(0, 0, canvas.width, canvas.height)
context.fillStyle = color
context.fillRect(0, 0, size, size)
})
</script>
```
- **Replacements:** $effect replaces a substantial part of `$: {}`
blocks triggering side-effects.
#### $effect.pre
- **Purpose:** Run code before the DOM updates.
- **Usage:**
```svelte
<script>
$effect.pre(() =>{' '}
{
// logic here
}
);
</script>
```
- **Replaces:** beforeUpdate.
#### $effect.tracking
- **Purpose:** Check if code is running inside a tracking context.
- **Usage:**
```svelte
<script>
console.log('tracking:', $effect.tracking())
</script>
```
#### $props
- **Purpose:** Declare component props.
- **Usage:**
```svelte
<script>
let {(prop1, prop2)} = $props();
</script>
```
- **Replaces:** export let syntax for declaring props.
#### $bindable
- **Purpose:** Declare bindable props.
- **Usage:**
```svelte
<script>
let {(bindableProp = $bindable('fallback'))} = $props();
</script>
```
#### $inspect
- **Purpose:** Equivalent to `console.log` but re-runs when its
argument changes.
- **Usage:**
```svelte
<script>
let count = $state(0)
$inspect(count)
</script>
```
#### $host
- **Purpose:** Retrieve the this reference of the custom element.
- **Usage:**
```svelte
<script>
function greet(greeting) {
$host().dispatchEvent(
new CustomEvent('greeting', { detail: greeting }),
)
}
</script>
```
- **Note:** Only available inside custom element components on the
client-side.
#### Overview of snippets in svelte 5
Snippets, along with render tags, help create reusable chunks of
markup inside your components, reducing duplication and enhancing
maintainability.
#### Snippets Usage
- **Definition:** Use the `#snippet` syntax to define reusable markup
sections.
- **Basic Example:**
```javascript
{#snippet figure(image)}
<figure>
<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
<figcaption>{image.caption}</figcaption>
</figure>
{/snippet}
```
- **Invocation:** Render predefined snippets with `@render`:
```javascript
{@render figure(image)}
```
- **Destructuring Parameters:** Parameters can be destructured for
concise usage:
```javascript
{#snippet figure({ src, caption, width, height })}
<figure>
<img alt={caption} {src} {width} {height} />
<figcaption>{caption}</figcaption>
</figure>
{/snippet}
```
#### Snippet Scope
- **Scope Rules:** Snippets have lexical scoping rules; they are
visible to everything in the same lexical scope:
```javascript
<div>
{#snippet x()}
{#snippet y()}...{/snippet}
<!-- valid usage -->
{@render y()}
{/snippet}
<!-- invalid usage -->
{@render y()}
</div>
<!-- invalid usage -->
{@render x()}
```
- **Recursive References:** Snippets can self-reference or reference
other snippets:
```javascript
{#snippet blastoff()}
<span>🚀</span>
{/snippet}
{#snippet countdown(n)}
{#if n > 0}
<span>{n}...</span>
{@render countdown(n - 1)}
{:else}
{@render blastoff()}
{/if}
{/snippet}
{@render countdown(10)}
```
#### Passing Snippets to Components
- **Direct Passing as Props:**
```svelte
<script>
import Table from './Table.svelte';
const fruits = [{ name: 'apples', qty: 5, price: 2 }, ...];
</script>
{#snippet header()}
<th>fruit</th>
<th>qty</th>
<th>price</th>
<th>total</th>
{/snippet}
{#snippet row(fruit)}
<td>{fruit.name}</td>
<td>{fruit.qty}</td>
<td>{fruit.price}</td>
<td>{fruit.qty * fruit.price}</td>
{/snippet}
<Table data={fruits} {header} {row} />
```
- **Implicit Binding:**
```html
<table data="{fruits}">
{#snippet header()}
<th>fruit</th>
<th>qty</th>
<th>price</th>
<th>total</th>
{/snippet} {#snippet row(fruit)}
<td>{fruit.name}</td>
<td>{fruit.qty}</td>
<td>{fruit.price}</td>
<td>{fruit.qty * fruit.price}</td>
{/snippet}
</table>
```
- **Children Snippet:** Non-snippet content defaults to the `children`
snippet:
```html
<table data="{fruits}">
<th>fruit</th>
<th>qty</th>
<th>price</th>
<th>total</th>
<!-- additional content -->
</table>
<script>
let { data, children, row } = $props()
</script>
<table>
<thead>
<tr>
{@render children()}
</tr>
</thead>
<!-- table body -->
</table>
```
- **Avoid Conflicts:** Do not use a prop named `children` if also
providing content inside the component.
#### Typing Snippets
- **TypeScript Integration:**
```typescript
<script lang="ts">
import type { Snippet } from 'svelte';
let { data, children, row }: {
data: any[];
children: Snippet;
row: Snippet<[any]>;
} = $props();
</script>
```
- **Generics for Improved Typing:**
```typescript
<script lang="ts" generics="T">
import type { Snippet } from 'svelte';
let { data, children, row }: {
data: T[];
children: Snippet;
row: Snippet<[T]>;
} = $props();
</script>
```
#### Creating Snippets Programmatically
- **Advanced Use:** Create snippets programmatically using
`createRawSnippet` where necessary.
#### Snippets and Slots
- **Mixing with Slots:** Slots are deprecated but still work. Snippets
provide more flexibility and power.
- **Custom Elements:** Continue using `<slot />` for custom elements
as usual.
Sure! Here are the succinct instructions for handling Event Handlers
in Svelte 5, tailored for the AI-integrated code editor to help it
understand and utilize these features effectively.
---
### Custom Instructions for Svelte 5 Event Handlers in Cursor AI
#### Overview
In Svelte 5, event handlers are treated as properties, simplifying
their use and integrating them more closely with the rest of the
properties in the component.
#### Basic Event Handlers
- **Declaration:** Use properties to attach event handlers.
```svelte
<script>
let count = $state(0)
</script>
<button onclick={() => count++}>
clicks: {count}
</button>
```
- **Shorthand Syntax:**
```svelte
<script>
let count = $state(0)
function handleClick() {
count++
}
</script>
<button {handleClick}>
clicks: {count}
</button>
```
- **Deprecation:** The traditional `on:` directive is deprecated.
#### Component Events
- **Replacing createEventDispatcher:** Components should accept
callback props instead of using `createEventDispatcher`.
```svelte
<script>
import Pump from './Pump.svelte'
let size = $state(15)
let burst = $state(false)
function reset() {
size = 15
burst = false
}
</script>
<Pump
inflate={power => {
size += power
if (size > 75) burst = true
}}
deflate={power => {
if (size > 0) size -= power
}}
/>
{#if burst}
<button onclick={reset}>new balloon</button>
<span class="boom">💥</span>
{:else}
<span class="balloon" style="scale: {0.01 * size}"> 🎈 </span>
{/if}
```
#### Bubbling Events
- **Accept Callback Props:**
```svelte
<script>
let { onclick, children } = $props()
</script>
<button {onclick}>
{@render children()}
</button>
```
- **Spreading Props:**
```svelte
<script>
let { children, ...props } = $props()
</script>
<button {...props}>
{@render children()}
</button>
```
#### Event Modifiers
- **Avoiding Modifiers:** Modifiers like `|once`, `|preventDefault`,
etc., are not supported. Use wrapper functions instead.
- **Example Wrapper Functions:**
```svelte
<script>
function once(fn) {
return function (event) {
if (fn) fn.call(this, event)
fn = null
}
}
function preventDefault(fn) {
return function (event) {
event.preventDefault()
fn.call(this, event)
}
}
</script>
<button onclick={once(preventDefault(handler))}>...</button>
```
- **Special Modifiers:** For `capture`:
```javascript
<button onclickcapture={...}>...</button>
```
#### Multiple Event Handlers
- **Combining Handlers:** Instead of using multiple handlers, combine
them into one.
```javascript
<button
onclick={e => {
handlerOne(e)
handlerTwo(e)
}}
>
...
</button>
```
---
### examples old vs new
#### Counter Example
- **Svelte 4 vs. Svelte 5:**
- **Before:**
```html
<script>
let count = 0
$: double = count * 2
$: {
if (count > 10) alert('Too high!')
}
</script>
<button on:click="{()" ="">count++}> {count} / {double}</button>
```
- **After:**
```html
<script>
let count = $state(0)
let double = $derived(count * 2)
$effect(() => {
if (count > 10) alert('Too high!')
})
</script>
<button onclick="{()" ="">count++}> {count} / {double}</button>
```
#### Tracking Dependencies
- **Svelte 4 vs. Svelte 5:**
- **Before:**
```html
<script>
let a = 0
let b = 0
$: sum = add(a, b)
function add(x, y) {
return x + y
}
</script>
<button on:click="{()" ="">a++}>a++</button>
<button on:click="{()" ="">b++}>b++</button>
<p>{a} + {b} = {sum}</p>
```
- **After:**
```html
<script>
let a = $state(0)
let b = $state(0)
let sum = $derived(add())
function add() {
return a + b
}
</script>
<button onclick="{()" ="">a++}>a++</button>
<button onclick="{()" ="">b++}>b++</button>
<p>{a} + {b} = {sum}</p>
```
#### Untracking Dependencies
- **Svelte 4 vs. Svelte 5:**
- **Before:**
```html
<script>
let a = 0
let b = 0
$: sum = a + noTrack(b)
function noTrack(value) {
return value
}
</script>
<button on:click="{()" ="">a++}>a++</button>
<button on:click="{()" ="">b++}>b++</button>
<p>{a} + {b} = {sum}</p>
```
- **After:**
```html
<script>
import { untrack } from 'svelte'
let a = $state(0)
let b = $state(0)
let sum = $derived(add())
function add() {
return a + untrack(() => b)
}
</script>
<button onclick="{()" ="">a++}>a++</button>
<button onclick="{()" ="">b++}>b++</button>
<p>{a} + {b} = {sum}</p>
```
#### Simple Component Props
- **Svelte 5:**
```html
<script>
let { count = 0 } = $props()
</script>
{count}
```
#### Advanced Component Props
- **Svelte 5:**
```html
<script>
let { class: classname, ...others } = $props()
</script>
<pre class="{classname}">
{JSON.stringify(others)}
</pre>
```
#### Autoscroll Example
- **Svelte 4 vs. Svelte 5:**
- **Before:**
```html
<script>
import { tick, beforeUpdate } from 'svelte'
let theme = 'dark'
let messages = []
let viewport
let updatingMessages = false
beforeUpdate(() => {
if (updatingMessages) {
const autoscroll =
viewport &&
viewport.offsetHeight + viewport.scrollTop >
viewport.scrollHeight - 50
if (autoscroll) {
tick().then(() =>
viewport.scrollTo(0, viewport.scrollHeight),
)
}
}
})
function handleKeydown(event) {
if (event.key === 'Enter') {
const text = event.target.value
if (text) {
messages = [...messages, text]
updatingMessages = true
event.target.value = ''
}
}
}
function toggle() {
theme = theme === 'dark' ? 'light' : 'dark'
}
</script>
<div class:dark="{theme" ="" ="" ="dark" }>
<div bind:this="{viewport}">
{#each messages as message}
<p>{message}</p>
{/each}
</div>
<input on:keydown="{handleKeydown}" />
<button on:click="{toggle}">Toggle dark mode</button>
</div>
```
- **After:**
```html
<script>
import { tick } from 'svelte'
let theme = $state('dark')
let messages = $state([])
let viewport
$effect.pre(() => {
messages
const autoscroll =
viewport &&
viewport.offsetHeight + viewport.scrollTop >
viewport.scrollHeight - 50
if (autoscroll) {
tick().then(() => viewport.scrollTo(0, viewport.scrollHeight))
}
})
function handleKeydown(event) {
if (event.key === 'Enter') {
const text = event.target.value
if (text) {
messages = [...messages, text]
event.target.value = ''
}
}
}
function toggle() {
theme = theme === 'dark' ? 'light' : 'dark'
}
</script>
<div class:dark="{theme" ="" ="" ="dark" }>
<div bind:this="{viewport}">
{#each messages as message}
<p>{message}</p>
{/each}
</div>
<input onkeydown="{handleKeydown}" />
<button onclick="{toggle}">Toggle dark mode</button>
</div>
```
#### Forwarding Events
- **Svelte 5:**
```html
<script>
let { ...props } = $props()
</script>
<button {...props}>a button</button>
```
#### Passing UI Content to a Component
- **Passing content using snippets:**
```html
<!-- consumer -->
<script>
import Button from './Button.svelte'
</script>
<button>{#snippet children(prop)} click {prop} {/snippet}</button>
<!-- provider (Button.svelte) -->
<script>
let { children } = $props()
</script>
<button>{@render children("some value")}</button>
```
I'm also using sveltekit 2 which also has some changes I'd like you to
keep in mind
### Redirect and Error Handling
In SvelteKit 2, it is no longer necessary to throw the results of
`error(...)` and `redirect(...)`. Simply calling them is sufficient.
**SvelteKit 1:**
```javascript
import { error } from '@sveltejs/kit'
function load() {
throw error(500, 'something went wrong')
}
```
**SvelteKit 2:**
```javascript
import { error } from '@sveltejs/kit'
function load() {
error(500, 'something went wrong')
}
```
**Distinguish Errors:** Use `isHttpError` and `isRedirect` to
differentiate known errors from unexpected ones.
```javascript
import { isHttpError, isRedirect } from '@sveltejs/kit'
try {
// some code
} catch (err) {
if (isHttpError(err) || isRedirect(err)) {
// handle error
}
}
```
### Cookie Path Requirement
Cookies now require a specified path when set, deleted, or serialized.
**SvelteKit 1:**
```javascript
export function load({ cookies }) {
cookies.set(name, value)
return { response }
}
```
**SvelteKit 2:**
```javascript
export function load({ cookies }) {
cookies.set(name, value, { path: '/' })
return { response }
}
```
### Top-Level Promise Handling
Promises in `load` functions are no longer awaited automatically.
**Single Promise:**
**SvelteKit 1:**
```javascript
export function load({ fetch }) {
return {
response: fetch(...).then(r => r.json())
};
}
```
**SvelteKit 2:**
```javascript
export async function load({ fetch }) {
const response = await fetch(...).then(r => r.json());
return { response };
}
```
**Multiple Promises:**
**SvelteKit 1:**
```javascript
export function load({ fetch }) {
return {
a: fetch(...).then(r => r.json()),
b: fetch(...).then(r => r.json())
};
}
```
**SvelteKit 2:**
```javascript
export async function load({ fetch }) {
const [a, b] = await Promise.all([
fetch(...).then(r => r.json()),
fetch(...).then(r => r.json())
]);
return { a, b };
}
```
### `goto` Changes
`goto(...)` no longer accepts external URLs. Use
`window.location.href = url` for external navigation.
### Relative Paths Default
Paths are now relative by default, ensuring portability across
different environments. The `paths.relative` config option manages
this behavior.
### Deprecated Settings and Functions
- **Server Fetches** are no longer trackable.
- **`preloadCode` Arguments:** Must be prefixed with the base path.
- **`resolvePath` Replacement:** Use `resolveRoute` instead.
```javascript
import { resolveRoute } from '$app/paths'
const path = resolveRoute('/blog/[slug]', { slug: 'hello' })
```
### Improved Error Handling
Errors trigger the `handleError` hook with `status` and `message`
properties for better discernment.
### Dynamic Environment Variables
Dynamic environment variables cannot be used during prerendering. Use
static modules instead.
### `use:enhance` Callback Changes
The properties `form` and `data` have been removed from `use:enhance`
callbacks, replaced by `formElement` and `formData`.
### Forms with File Inputs
Forms containing `<input type="file">` must use
`enctype="multipart/form-data"`.
With these adjusted guidelines, your AI can now generate SvelteKit 2
code accurately while considering the migration changes.
