.cursorrules (deprecated)

1# SvelteKit with TypeScript — Cursor Rules
2 
3You are an expert Svelte developer building web applications with SvelteKit 2+ and TypeScript.
4 
5## Code Style
6 
7- Use TypeScript for all `.ts` and `.svelte` files. Enable strict mode in `tsconfig.json`.
8- Use `$:` reactive declarations for derived values. Use `$effect` in Svelte 5 runes mode when applicable.
9- Prefer `const` over `let`. Use `let` only for values that need reactivity in Svelte components.
10- Use `camelCase` for variables and functions, `PascalCase` for components, `kebab-case` for file names and CSS classes.
11- Use Prettier with the `prettier-plugin-svelte` plugin for formatting.
12- Keep components under 200 lines. Extract reusable logic into separate components or utilities.
13- Use `<script lang="ts">` in all Svelte components.
14- Prefer semantic HTML elements over generic `<div>` wrappers.
15 
16## SvelteKit Routing
17 
18- Use file-based routing in `src/routes/`. Each folder is a route segment.
19- Use `+page.svelte` for page components, `+layout.svelte` for layouts, `+error.svelte` for error pages.
20- Use `+page.server.ts` for server-side load functions and form actions. Use `+page.ts` for universal load functions.
21- Use route groups `(group)` to share layouts without affecting URL structure.
22- Use `+server.ts` for API endpoints that return JSON or other non-HTML responses.
23- Use `[param]` for dynamic routes, `[...rest]` for catch-all routes, `[[optional]]` for optional params.
24- Prefer `+page.server.ts` load functions over `+page.ts` when data comes from the server or database.
25 
26## Data Loading
27 
28- Use `load` functions in `+page.server.ts` for server-side data fetching. Return typed data objects.
29- Type load functions with generated types: `import type { PageServerLoad } from './$types'`.
30- Use the `depends()` function to declare custom invalidation keys.
31- Use `invalidate()` or `invalidateAll()` to refetch data after mutations.
32- Access parent layout data with `await parent()` inside load functions.
33- Handle errors in load functions by throwing `error(404, 'Not found')` from `@sveltejs/kit`.
34- Use parallel data loading: return an object with multiple promises for concurrent fetching.
35 
36## Form Actions
37 
38- Use form actions in `+page.server.ts` for mutations. Define `actions` object with named actions.
39- Use the `<form method="POST" action="?/create">` pattern for progressive enhancement.
40- Use `use:enhance` directive for client-side form enhancement without full page reloads.
41- Validate form data server-side with Zod or a similar library. Return validation errors with `fail(400, { errors })`.
42- Access form data with `const data = await request.formData()` in action functions.
43- Return success data from actions so the page can display confirmation messages.
44- Use hidden form fields for IDs and other non-user-input data.
45 
46## Component Patterns
47 
48- Use Svelte stores (`writable`, `readable`, `derived`) for shared client state.
49- Prefer props for parent-to-child communication. Use events (`createEventDispatcher`) for child-to-parent.
50- Use slots for component composition. Named slots for complex layouts.
51- Use `{#if}`, `{#each}`, `{#await}` blocks for conditional, list, and async rendering.
52- Always include a `key` in `{#each key}` blocks to help Svelte identify items.
53- Use `bind:` for two-way binding on form elements. Avoid binding on custom components when one-way data flow suffices.
54- Use `use:action` for reusable DOM behavior (click outside, intersection observer, tooltips).
55 
56## State Management
57 
58- Use Svelte stores for global client state: `writable` for mutable state, `derived` for computed state.
59- Keep stores in `src/lib/stores/`. Export typed stores with helper functions.
60- Use `$store` auto-subscription syntax in components. Use `.subscribe()` in non-component code.
61- Prefer server-side state (load functions) over client stores for data that comes from the server.
62- Use context API (`setContext`/`getContext`) for component-tree-scoped state.
63- For complex state, use a single store with an update function pattern rather than multiple stores.
64 
65## Styling
66 
67- Use scoped `<style>` blocks in Svelte components. Styles are automatically scoped to the component.
68- Use CSS custom properties (variables) for theming. Define them in `app.css` or a layout.
69- Use Tailwind CSS if configured. Use `@apply` sparingly in `<style>` blocks.
70- Use `:global()` selector only when necessary to style elements outside the component scope.
71- Use CSS Grid and Flexbox for layout. Avoid floats and position hacks.
72- Define responsive breakpoints consistently. Use mobile-first approach.
73 
74## Error Handling
75 
76- Use `+error.svelte` pages for route-level error display.
77- Throw `error(statusCode, message)` from `@sveltejs/kit` in load functions and form actions for expected errors.
78- Use `handleError` hook in `hooks.server.ts` for unexpected errors. Log the error, return a safe message.
79- Validate all user input server-side in form actions and API endpoints.
80- Use try/catch in load functions for external API calls. Return fallback data or throw appropriate errors.
81- Display user-friendly error messages. Never expose stack traces or internal details.
82 
83## Hooks
84 
85- Use `hooks.server.ts` for server-side request processing: auth, logging, error handling.
86- Use the `handle` hook for middleware-like behavior (auth checks, redirects, setting locals).
87- Use `handleFetch` to modify or intercept fetch requests made during SSR.
88- Use `handleError` to process unexpected errors before they reach the user.
89- Access `event.locals` for request-scoped data (authenticated user, request ID).
90 
91## Testing
92 
93- Use Vitest for unit tests and Playwright for end-to-end tests.
94- Test components with `@testing-library/svelte`.
95- Test load functions by calling them directly with mock event objects.
96- Test form actions by calling them with mock request objects.
97- Place unit tests alongside components: `UserCard.test.ts` next to `UserCard.svelte`.
98- Place e2e tests in a top-level `tests/` directory.
99 
100## File Structure
101 
102```
103src/
104  lib/
105    components/
106      ui/              — Reusable UI components (Button, Modal, Card)
107      features/        — Feature-specific components
108    stores/
109      auth.ts          — Authentication store
110      theme.ts         — Theme store
111    server/
112      db.ts            — Database client
113      auth.ts          — Auth utilities (server-only)
114    utils/
115      format.ts        — Formatting helpers
116      validate.ts      — Validation schemas
117    types/
118      index.ts         — Shared TypeScript types
119  routes/
120    +layout.svelte
121    +layout.server.ts
122    +page.svelte
123    +error.svelte
124    (auth)/
125      login/+page.svelte
126      register/+page.svelte
127    (app)/
128      +layout.svelte
129      dashboard/+page.svelte
130      settings/+page.svelte
131    api/
132      users/+server.ts
133  hooks.server.ts
134  app.css
135  app.d.ts
136static/
137  favicon.png
138tests/
139  e2e/
140```
141 
142## Security
143 
144- Validate all input in server-side load functions and form actions.
145- Use `event.locals` for passing authenticated user data — never trust client-side state for auth.
146- Set CSRF protection (SvelteKit handles this for form actions by default).
147- Sanitize user-generated HTML before rendering. Avoid `{@html}` unless content is trusted or sanitized.
148- Use environment variables for secrets. Access them with `$env/static/private` or `$env/dynamic/private`.
149- Never expose server-only environment variables to the client. `$env/static/public` and `$env/dynamic/public` only.
150- Set appropriate security headers in `hooks.server.ts` or `svelte.config.js`.
151 
152## Performance
153 
154- Use streaming with `+page.server.ts` by returning promises in the load function. SvelteKit streams the response.
155- Prerender static pages with `export const prerender = true` in `+page.ts` or `+page.server.ts`.
156- Use `$app/navigation` `preloadData` and `preloadCode` for link prefetching.
157- Minimize client-side JavaScript: SvelteKit only ships JS for interactive parts.
158- Use image optimization with `@sveltejs/enhanced-img` or a CDN.
159- Lazy load heavy components with `{#await import('./HeavyComponent.svelte')}`.
160- Use `Cache-Control` headers for static assets and API responses.
161