.cursorrules (deprecated)

1# SvelteKit — Cursor Rules
2# Comprehensive rules for SvelteKit application development
3 
4## Project Context
5You are working on a SvelteKit application. The project uses Svelte 5 runes for
6reactivity, SvelteKit for routing and server-side rendering, and TypeScript for type
7safety. SvelteKit provides file-based routing, server-side rendering, and a clear
8separation between server and client code.
9 
10## Tech Stack
11- Svelte 5 with runes ($state, $derived, $effect)
12- SvelteKit 2+ with file-based routing
13- TypeScript (strict mode)
14- Vite for building
15- Tailwind CSS or vanilla CSS for styling
16- Superforms or native form handling
17- Vitest + Playwright for testing
18 
19## Coding Style
20 
21### Naming Conventions
22- Components: PascalCase (e.g., `UserProfile.svelte`, `DataTable.svelte`)
23- Route files: `+page.svelte`, `+page.server.ts`, `+layout.svelte`, `+server.ts`
24- Stores: camelCase with descriptive names (e.g., `userStore.ts`, `cartItems.svelte.ts`)
25- Utility functions: camelCase (e.g., `formatDate.ts`, `validateEmail.ts`)
26- CSS classes: kebab-case or Tailwind utilities
27- Events: kebab-case (e.g., `on:item-selected`)
28 
29### File Structure
30```
31src/
32  routes/
33    +page.svelte              # Home page
34    +layout.svelte            # Root layout
35    +layout.server.ts         # Root layout server load
36    (app)/                    # Route group for authenticated pages
37      dashboard/
38        +page.svelte
39        +page.server.ts
40    (marketing)/              # Route group for public pages
41      about/
42        +page.svelte
43    api/
44      webhooks/
45        +server.ts            # API endpoint
46  lib/
47    components/               # Shared components
48      ui/                     # UI primitives
49    server/                   # Server-only modules (database, auth)
50    utils/                    # Shared utilities
51    types/                    # TypeScript types
52    stores/                   # Svelte stores / rune-based state
53  hooks.server.ts             # Server hooks (auth, logging)
54  hooks.client.ts             # Client hooks (error handling)
55```
56 
57## Svelte 5 Runes
58 
59### State Management
60```svelte
61<script lang="ts">
62  // Reactive state with $state
63  let count = $state(0);
64  let user = $state<User | null>(null);
65 
66  // Derived values with $derived
67  let doubled = $derived(count * 2);
68  let isLoggedIn = $derived(user !== null);
69 
70  // Complex derived with $derived.by
71  let summary = $derived.by(() => {
72    if (!user) return 'Not logged in';
73    return `${user.name} (${user.email})`;
74  });
75 
76  // Side effects with $effect
77  $effect(() => {
78    console.log('Count changed to', count);
79    // Cleanup function (optional)
80    return () => { /* cleanup */ };
81  });
82</script>
83```
84 
85### Props with Runes
86```svelte
87<script lang="ts">
88  interface Props {
89    title: string;
90    count?: number;
91    onUpdate?: (value: number) => void;
92    children: import('svelte').Snippet;
93  }
94 
95  let { title, count = 0, onUpdate, children }: Props = $props();
96</script>
97```
98 
99### Prefer
100- Svelte 5 runes (`$state`, `$derived`, `$effect`) over Svelte 4 stores
101- `$derived` over `$effect` for computing values (no unnecessary side effects)
102- `$props()` for component inputs
103- Snippets over slots for content projection (Svelte 5)
104- `.svelte.ts` files for shared reactive state modules
105- Form actions for form handling
106- `$lib/` alias for imports from `src/lib/`
107 
108### Avoid
109- Svelte 4 syntax (`export let`, `$:` reactive declarations, `$$props`)
110- Writable stores for local component state — use `$state` instead
111- `$effect` for derived values — use `$derived` instead
112- Direct DOM manipulation — use Svelte's reactivity
113- `onMount` when `$effect` serves the same purpose
114- Overusing context for simple prop passing
115 
116## SvelteKit Data Loading
117 
118### Server Load Functions
119```ts
120// +page.server.ts
121import type { PageServerLoad } from './$types';
122import { error, redirect } from '@sveltejs/kit';
123 
124export const load: PageServerLoad = async ({ params, locals, depends }) => {
125  depends('app:posts'); // For invalidation
126 
127  const post = await db.post.findUnique({ where: { slug: params.slug } });
128  if (!post) error(404, 'Post not found');
129 
130  return { post };
131};
132```
133 
134### Universal Load Functions
135```ts
136// +page.ts — runs on both server and client
137import type { PageLoad } from './$types';
138 
139export const load: PageLoad = async ({ fetch, params }) => {
140  const response = await fetch(`/api/posts/${params.id}`);
141  return { post: await response.json() };
142};
143```
144 
145### Form Actions
146```ts
147// +page.server.ts
148import type { Actions } from './$types';
149import { fail, redirect } from '@sveltejs/kit';
150 
151export const actions: Actions = {
152  create: async ({ request, locals }) => {
153    const formData = await request.formData();
154    const title = formData.get('title')?.toString();
155 
156    if (!title || title.length < 3) {
157      return fail(400, { title, error: 'Title must be at least 3 characters' });
158    }
159 
160    const post = await db.post.create({ data: { title, authorId: locals.user.id } });
161    redirect(303, `/posts/${post.id}`);
162  },
163 
164  delete: async ({ params, locals }) => {
165    await db.post.delete({ where: { id: params.id, authorId: locals.user.id } });
166    redirect(303, '/posts');
167  },
168};
169```
170 
171## Error Handling
172- Use `error()` helper in load functions for expected errors (404, 403)
173- Use `fail()` in form actions for validation errors
174- Create `+error.svelte` pages for error UI at each route level
175- Use `handleError` hook in `hooks.server.ts` for unexpected server errors
176- Always provide user-friendly error messages
177- Log unexpected errors to an error tracking service
178 
179## API Routes
180```ts
181// routes/api/posts/+server.ts
182import { json, error } from '@sveltejs/kit';
183import type { RequestHandler } from './$types';
184 
185export const GET: RequestHandler = async ({ url, locals }) => {
186  const page = Number(url.searchParams.get('page')) || 1;
187  const posts = await db.post.findMany({ skip: (page - 1) * 20, take: 20 });
188  return json({ posts, page });
189};
190 
191export const POST: RequestHandler = async ({ request, locals }) => {
192  if (!locals.user) error(401, 'Unauthorized');
193  const body = await request.json();
194  const post = await db.post.create({ data: { ...body, authorId: locals.user.id } });
195  return json(post, { status: 201 });
196};
197```
198 
199## Testing
200- Use Vitest for unit tests of utilities, stores, and logic
201- Use `@testing-library/svelte` for component tests
202- Use Playwright for E2E tests via SvelteKit's integration
203- Test load functions as regular async functions
204- Test form actions by simulating FormData
205- Place tests in `src/tests/` or co-locate with `*.test.ts` files
206 
207## Performance Guidelines
208- Use streaming with `await parent()` wisely — avoid waterfalls
209- Preload data with `data-sveltekit-preload-data="hover"` on links
210- Use `{#key}` blocks sparingly — they destroy and recreate DOM
211- Lazy-load heavy components with dynamic imports
212- Use `$effect.pre()` only when you need to run before DOM update
213- Avoid expensive computations in `$derived` — memoize or debounce if needed
214 
215## Common Pitfalls
216- Forgetting to return data from load functions
217- Not using `$types` imports for proper type inference in load/actions
218- Using `$effect` to set state that could be `$derived`
219- Mutating `$state` arrays/objects — mutations ARE tracked in Svelte 5 (unlike React)
220- Not handling the `form` prop in `+page.svelte` after form actions
221- Forgetting that `+page.server.ts` load data is serialized (no functions, dates as strings)
222- Using `fetch` from `globalThis` instead of the `fetch` passed to load functions
223- Not calling `await parent()` when needed in nested load functions
224