# SvelteKit + shadcn-svelte
You are working in a SvelteKit 2 project with Svelte 5, TypeScript, shadcn-svelte components built on Bits UI, and Tailwind CSS v4. Write code for the versions in `package.json`, not the ones in your training data: Svelte 5 replaced most of Svelte 4's syntax with runes, snippets and event attributes, and the old syntax only survives in legacy mode.
## Before you write code
- Read `package.json` for `svelte`, `@sveltejs/kit`, `bits-ui` (or `@ark-ui/svelte`) and `tailwindcss`, and `svelte.config.js` for the adapter, aliases and any `experimental` flags.
- Read `components.json` for the aliases (usually `$lib/components/ui` and `$lib/utils`), and look in the UI folder before adding a component: it may exist, with local changes to keep.
- Use the generated types: `./$types` in every route file. Run `npx svelte-kit sync` (or the dev server) after adding routes so they exist.
## Svelte 5 runes
- State: `let count = $state(0)`. Objects and arrays become deeply reactive proxies; mutate them directly. Use `$state.raw` for large data you replace whole (API results, long lists).
- Derived values: `let total = $derived(items.length)`, or `$derived.by(() => { … })` for several lines. Never compute state inside `$effect`.
- `$effect` is for side effects outside Svelte (DOM APIs, timers, subscriptions, analytics); return a cleanup function. It never runs on the server, so it can't load page data.
- Props come from one `$props()` call, with defaults and the rest spread:
```svelte
```
- Mark a prop `$bindable()` only when the parent needs `bind:value`; otherwise pass a callback prop. `$props.id()` gives ids that match between server and client.
- `$inspect(value)` is for debugging: remove it before finishing.
- Shared reactive state lives in `.svelte.ts` modules as an object or class with `$state` fields; you can't export a `let` that you reassign. On the server, module state is shared by every request: keep per-user data in `event.locals`, load data or context (`createContext` returns a typed getter and setter).
- Use `SvelteMap`, `SvelteSet`, `SvelteURL` and `MediaQuery` from `svelte/reactivity` instead of wrapping built-ins by hand.
## Templates
- Events are attributes: `onclick={save}`, `oninput`, `onsubmit`. There are no modifiers: call `event.preventDefault()` in the handler.
- Components raise events through callback props (`onvaluechange`), not dispatched events.
- Content is passed as snippets: `children` rendered with `{@render children?.()}`, named ones declared with `{#snippet row(item)}…{/snippet}` and typed `Snippet<[Item]>`. A component stored in a variable renders as `` directly.
- Attach DOM behavior with `{@attach tooltip(text)}`: attachments re-run when their state changes and pass through spread props. Wrap an existing action with `fromAction` from `svelte/attachments` rather than writing a new `use:` action.
- `class` takes arrays and objects (`class={["card", selected && "ring-2", { "opacity-50": disabled }]}`); merge with a caller's class through `cn()`.
- Key every list: `{#each items as item (item.id)}`. Catch rendering errors in a region with `` and a `failed` snippet.
- Intercept a binding with function bindings: `bind:value={() => value, (next) => (value = next.trim())}`.
## Routes and loading
- Files in `src/routes`: `+page.svelte`, `+layout.svelte`, `+page.ts` (universal load: runs on the server and in the browser), `+page.server.ts` (server only: database, secrets, cookies), `+server.ts` (endpoints), `+error.svelte`. Groups are `(app)`, params `[id]`, optional `[[lang]]`, rest `[...path]`.
- Pages read their props with the generated types; layouts render `children`:
```svelte
```
- Write loads as `export const load: PageServerLoad = async ({ params, locals, depends }) => { … }`. In universal loads use the `fetch` argument, never the global one: it forwards cookies and doesn't refetch on hydration. Never fetch your own `+server.ts` from a server load: call the function it would call.
- Return only what the page renders, never whole rows with private fields. To stream slow data, return its promise un-awaited as a property of a server load and render it with `{#await data.comments}`.
- `error(404, "Not found")` and `redirect(303, "/login")` from `@sveltejs/kit` throw by themselves: call them without `throw`, and outside any `try` that would swallow them.
- Refresh data with `depends("app:posts")` plus `invalidate("app:posts")`, or `invalidateAll()`, from `$app/navigation`.
- Read the current page from `$app/state`: `page.url`, `page.params`, `page.data`, `page.form`, `navigating`. It replaces `$app/stores`.
- Navigate with plain ``; use `goto` for programmatic navigation inside the app only. Set `prerender`, `ssr` and `csr` as exports of `+page.ts` or `+layout.ts`.
## Forms and endpoints
- Mutations are form actions in `+page.server.ts`:
```ts
import { fail, redirect } from "@sveltejs/kit";
import { z } from "zod";
import type { Actions } from "./$types";
const Post = z.object({ title: z.string().trim().min(1).max(200) });
export const actions = {
create: async ({ request, locals }) => {
if (!locals.user) redirect(303, "/login");
const parsed = Post.safeParse(Object.fromEntries(await request.formData()));
if (!parsed.success) {
return fail(400, { errors: z.flattenError(parsed.error).fieldErrors });
}
await createPost(locals.user.id, parsed.data); // your data layer
},
} satisfies Actions;
```
- Post to them with `