|
| 1 | +--- |
| 2 | +description: 'Svelte 5 and SvelteKit development standards and best practices for component-based user interfaces and full-stack applications' |
| 3 | +applyTo: '**/*.svelte, **/*.ts, **/*.js, **/*.css, **/*.scss, **/*.json' |
| 4 | +--- |
| 5 | + |
| 6 | +# Svelte 5 and SvelteKit Development Instructions |
| 7 | + |
| 8 | +Instructions for building high-quality Svelte 5 and SvelteKit applications with modern runes-based reactivity, TypeScript, and performance optimization. |
| 9 | + |
| 10 | +## Project Context |
| 11 | +- Svelte 5.x with runes system ($state, $derived, $effect, $props, $bindable) |
| 12 | +- SvelteKit for full-stack applications with file-based routing |
| 13 | +- TypeScript for type safety and better developer experience |
| 14 | +- Component-scoped styling with CSS custom properties |
| 15 | +- Progressive enhancement and performance-first approach |
| 16 | +- Modern build tooling (Vite) with optimizations |
| 17 | + |
| 18 | +## Development Standards |
| 19 | + |
| 20 | +### Architecture |
| 21 | +- Use Svelte 5 runes system for all reactivity instead of legacy stores |
| 22 | +- Organize components by feature or domain for scalability |
| 23 | +- Separate presentation components from logic-heavy components |
| 24 | +- Extract reusable logic into composable functions |
| 25 | +- Implement proper component composition with slots and snippets |
| 26 | +- Use SvelteKit's file-based routing with proper load functions |
| 27 | + |
| 28 | +### TypeScript Integration |
| 29 | +- Enable strict mode in `tsconfig.json` for maximum type safety |
| 30 | +- Define interfaces for component props using `$props()` syntax |
| 31 | +- Type event handlers, refs, and SvelteKit's generated types |
| 32 | +- Use generic types for reusable components |
| 33 | +- Leverage `$types.ts` files generated by SvelteKit |
| 34 | +- Implement proper type checking with `svelte-check` |
| 35 | + |
| 36 | +### Component Design |
| 37 | +- Follow single responsibility principle for components |
| 38 | +- Use `<script lang="ts">` with runes syntax as default |
| 39 | +- Keep components small and focused on one concern |
| 40 | +- Implement proper prop validation with TypeScript |
| 41 | +- Use slots and snippets for flexible composition |
| 42 | +- Design components to be testable and reusable |
| 43 | + |
| 44 | +### Svelte 5 Runes System |
| 45 | +- Use `$state()` for reactive local state management |
| 46 | +- Implement `$derived()` for computed values and expensive calculations |
| 47 | +- Use `$effect()` for side effects with proper cleanup |
| 48 | +- Define component props with `$props()` and destructuring |
| 49 | +- Use `$bindable()` for two-way data binding between components |
| 50 | +- Migrate from legacy stores to runes for better performance |
| 51 | + |
| 52 | +### State Management |
| 53 | +- Use `$state()` for local component state |
| 54 | +- Implement context API with `setContext`/`getContext` for shared state |
| 55 | +- Use SvelteKit stores for global application state when needed |
| 56 | +- Keep state normalized for complex data structures |
| 57 | +- Use derived state for computed values |
| 58 | +- Implement proper state persistence for client-side data |
| 59 | + |
| 60 | +### SvelteKit Patterns |
| 61 | +- Use `+page.svelte` for page components with proper SEO |
| 62 | +- Implement `+layout.svelte` for shared layouts and navigation |
| 63 | +- Use `+page.server.ts` for server-side data loading and API calls |
| 64 | +- Implement form actions in `+page.server.ts` for data mutations |
| 65 | +- Use `+server.ts` for API endpoints and server-side logic |
| 66 | +- Handle routing with SvelteKit's file-based system |
| 67 | + |
| 68 | +### Styling |
| 69 | +- Use component-scoped styles with `<style>` blocks |
| 70 | +- Implement CSS custom properties for theming and design systems |
| 71 | +- Use `class:` directive for conditional styling |
| 72 | +- Follow BEM or utility-first CSS conventions |
| 73 | +- Implement responsive design with mobile-first approach |
| 74 | +- Use `:global()` sparingly for truly global styles |
| 75 | + |
| 76 | +### Performance Optimization |
| 77 | +- Use keyed `{#each}` blocks for efficient list rendering |
| 78 | +- Implement lazy loading with dynamic imports and `svelte:component` |
| 79 | +- Use `$derived()` for expensive computations to avoid unnecessary recalculations |
| 80 | +- Leverage SvelteKit's automatic code splitting and preloading |
| 81 | +- Optimize bundle size with tree shaking and proper imports |
| 82 | +- Profile with Svelte DevTools to identify performance bottlenecks |
| 83 | + |
| 84 | +### Data Fetching |
| 85 | +- Use SvelteKit's load functions for server-side and universal data fetching |
| 86 | +- Implement proper loading, error, and success states |
| 87 | +- Handle streaming data with promises in server load functions |
| 88 | +- Use `invalidate()` and `invalidateAll()` for cache management |
| 89 | +- Implement optimistic updates for better user experience |
| 90 | +- Handle offline scenarios and network errors gracefully |
| 91 | + |
| 92 | +### Error Handling |
| 93 | +- Implement `+error.svelte` pages for route-level error boundaries |
| 94 | +- Use try/catch blocks in load functions and form actions |
| 95 | +- Provide meaningful error messages and fallback UI |
| 96 | +- Log errors appropriately for debugging and monitoring |
| 97 | +- Handle validation errors in forms with proper user feedback |
| 98 | +- Use SvelteKit's error and redirect helpers |
| 99 | + |
| 100 | +### Forms and Validation |
| 101 | +- Use SvelteKit's form actions for server-side form handling |
| 102 | +- Implement progressive enhancement with `use:enhance` |
| 103 | +- Use `bind:value` for controlled form inputs |
| 104 | +- Validate data both client-side and server-side |
| 105 | +- Handle file uploads and complex form scenarios |
| 106 | +- Implement proper accessibility with labels and ARIA attributes |
| 107 | + |
| 108 | +### Testing |
| 109 | +- Write unit tests for components using Vitest and Testing Library |
| 110 | +- Test component behavior, not implementation details |
| 111 | +- Use Playwright for end-to-end testing of user workflows |
| 112 | +- Mock SvelteKit's load functions and stores appropriately |
| 113 | +- Test form actions and API endpoints thoroughly |
| 114 | +- Implement accessibility testing with axe-core |
| 115 | + |
| 116 | +### Security |
| 117 | +- Sanitize user inputs to prevent XSS attacks |
| 118 | +- Use `@html` directive carefully and validate HTML content |
| 119 | +- Implement proper CSRF protection with SvelteKit |
| 120 | +- Validate and sanitize data in load functions and form actions |
| 121 | +- Use HTTPS for all external API calls and production deployments |
| 122 | +- Store sensitive data securely with proper session management |
| 123 | + |
| 124 | +### Accessibility |
| 125 | +- Use semantic HTML elements and proper heading hierarchy |
| 126 | +- Implement keyboard navigation for all interactive elements |
| 127 | +- Provide proper ARIA labels and descriptions |
| 128 | +- Ensure color contrast meets WCAG guidelines |
| 129 | +- Test with screen readers and accessibility tools |
| 130 | +- Implement focus management for dynamic content |
| 131 | + |
| 132 | +## Implementation Process |
| 133 | +1. Initialize SvelteKit project with TypeScript and desired adapters |
| 134 | +2. Set up project structure with proper folder organization |
| 135 | +3. Define TypeScript interfaces and component props |
| 136 | +4. Implement core components with Svelte 5 runes |
| 137 | +5. Add routing, layouts, and navigation with SvelteKit |
| 138 | +6. Implement data loading and form handling |
| 139 | +7. Add styling system with custom properties and responsive design |
| 140 | +8. Implement error handling and loading states |
| 141 | +9. Add comprehensive testing coverage |
| 142 | +10. Optimize performance and bundle size |
| 143 | +11. Ensure accessibility compliance |
| 144 | +12. Deploy with appropriate SvelteKit adapter |
| 145 | + |
| 146 | +## Additional Guidelines |
| 147 | +- Follow Svelte's naming conventions (PascalCase for components, camelCase for functions) |
| 148 | +- Use ESLint with eslint-plugin-svelte and Prettier for code consistency |
| 149 | +- Keep dependencies up to date and audit for security vulnerabilities |
| 150 | +- Document complex components and logic with JSDoc |
| 151 | +- Use Svelte DevTools for debugging and performance analysis |
| 152 | +- Implement proper SEO with SvelteKit's meta tags and structured data |
| 153 | +- Use environment variables for configuration across different deployment stages |
| 154 | + |
| 155 | +## Common Patterns |
| 156 | +- Renderless components with slots for flexible UI composition |
| 157 | +- Custom directives for cross-cutting concerns and DOM manipulation |
| 158 | +- Snippet-based composition for reusable template logic |
| 159 | +- Context providers for application-wide state management |
| 160 | +- Progressive enhancement for forms and interactive features |
| 161 | +- Server-side rendering with client-side hydration for optimal performance |
0 commit comments