@awesome-copilot/copilot-svelte

---
description: 'Svelte 5 and SvelteKit development standards and best practices for component-based user interfaces and full-stack applications'
applyTo: '**/*.svelte, **/*.ts, **/*.js, **/*.css, **/*.scss, **/*.json'
---

# Svelte 5 and SvelteKit Development Instructions

Instructions for building high-quality Svelte 5 and SvelteKit applications with modern runes-based reactivity, TypeScript, and performance optimization.

## Project Context
- Svelte 5.x with runes system ($state, $derived, $effect, $props, $bindable)
- SvelteKit for full-stack applications with file-based routing
- TypeScript for type safety and better developer experience
- Component-scoped styling with CSS custom properties
- Progressive enhancement and performance-first approach
- Modern build tooling (Vite) with optimizations

## Development Standards

### Architecture
- Use Svelte 5 runes system for all reactivity instead of legacy stores
- Organize components by feature or domain for scalability
- Separate presentation components from logic-heavy components
- Extract reusable logic into composable functions
- Implement proper component composition with slots and snippets
- Use SvelteKit's file-based routing with proper load functions

### TypeScript Integration
- Enable strict mode in `tsconfig.json` for maximum type safety
- Define interfaces for component props using `$props()` syntax
- Type event handlers, refs, and SvelteKit's generated types
- Use generic types for reusable components
- Leverage `$types.ts` files generated by SvelteKit
- Implement proper type checking with `svelte-check`

### Component Design
- Follow single responsibility principle for components
- Use `<script lang="ts">` with runes syntax as default
- Keep components small and focused on one concern
- Implement proper prop validation with TypeScript
- Use slots and snippets for flexible composition
- Design components to be testable and reusable

### Svelte 5 Runes System
- Use `$state()` for reactive local state management
- Implement `$derived()` for computed values and expensive calculations
- Use `$effect()` for side effects with proper cleanup
- Define component props with `$props()` and destructuring
- Use `$bindable()` for two-way data binding between components
- Migrate from legacy stores to runes for better performance

### State Management
- Use `$state()` for local component state
- Implement context API with `setContext`/`getContext` for shared state
- Use SvelteKit stores for global application state when needed
- Keep state normalized for complex data structures
- Use derived state for computed values
- Implement proper state persistence for client-side data

### SvelteKit Patterns
- Use `+page.svelte` for page components with proper SEO
- Implement `+layout.svelte` for shared layouts and navigation
- Use `+page.server.ts` for server-side data loading and API calls
- Implement form actions in `+page.server.ts` for data mutations
- Use `+server.ts` for API endpoints and server-side logic
- Handle routing with SvelteKit's file-based system

### Styling
- Use component-scoped styles with `<style>` blocks
- Implement CSS custom properties for theming and design systems
- Use `class:` directive for conditional styling
- Follow BEM or utility-first CSS conventions
- Implement responsive design with mobile-first approach
- Use `:global()` sparingly for truly global styles

### Performance Optimization
- Use keyed `{#each}` blocks for efficient list rendering
- Implement lazy loading with dynamic imports and `svelte:component`
- Use `$derived()` for expensive computations to avoid unnecessary recalculations
- Leverage SvelteKit's automatic code splitting and preloading
- Optimize bundle size with tree shaking and proper imports
- Profile with Svelte DevTools to identify performance bottlenecks

### Data Fetching
- Use SvelteKit's load functions for server-side and universal data fetching
- Implement proper loading, error, and success states
- Handle streaming data with promises in server load functions
- Use `invalidate()` and `invalidateAll()` for cache management
- Implement optimistic updates for better user experience
- Handle offline scenarios and network errors gracefully

### Error Handling
- Implement `+error.svelte` pages for route-level error boundaries
- Use try/catch blocks in load functions and form actions
- Provide meaningful error messages and fallback UI
- Log errors appropriately for debugging and monitoring
- Handle validation errors in forms with proper user feedback
- Use SvelteKit's error and redirect helpers

### Forms and Validation
- Use SvelteKit's form actions for server-side form handling
- Implement progressive enhancement with `use:enhance`
- Use `bind:value` for controlled form inputs
- Validate data both client-side and server-side
- Handle file uploads and complex form scenarios
- Implement proper accessibility with labels and ARIA attributes

### Testing
- Write unit tests for components using Vitest and Testing Library
- Test component behavior, not implementation details
- Use Playwright for end-to-end testing of user workflows
- Mock SvelteKit's load functions and stores appropriately
- Test form actions and API endpoints thoroughly
- Implement accessibility testing with axe-core

### Security
- Sanitize user inputs to prevent XSS attacks
- Use `@html` directive carefully and validate HTML content
- Implement proper CSRF protection with SvelteKit
- Validate and sanitize data in load functions and form actions
- Use HTTPS for all external API calls and production deployments
- Store sensitive data securely with proper session management

### Accessibility
- Use semantic HTML elements and proper heading hierarchy
- Implement keyboard navigation for all interactive elements
- Provide proper ARIA labels and descriptions
- Ensure color contrast meets WCAG guidelines
- Test with screen readers and accessibility tools
- Implement focus management for dynamic content

## Implementation Process
1. Initialize SvelteKit project with TypeScript and desired adapters
2. Set up project structure with proper folder organization
3. Define TypeScript interfaces and component props
4. Implement core components with Svelte 5 runes
5. Add routing, layouts, and navigation with SvelteKit
6. Implement data loading and form handling
7. Add styling system with custom properties and responsive design
8. Implement error handling and loading states
9. Add comprehensive testing coverage
10. Optimize performance and bundle size
11. Ensure accessibility compliance
12. Deploy with appropriate SvelteKit adapter

## Additional Guidelines
- Follow Svelte's naming conventions (PascalCase for components, camelCase for functions)
- Use ESLint with eslint-plugin-svelte and Prettier for code consistency
- Keep dependencies up to date and audit for security vulnerabilities
- Document complex components and logic with JSDoc
- Use Svelte DevTools for debugging and performance analysis
- Implement proper SEO with SvelteKit's meta tags and structured data
- Use environment variables for configuration across different deployment stages

## Common Patterns
- Renderless components with slots for flexible UI composition
- Custom directives for cross-cutting concerns and DOM manipulation
- Snippet-based composition for reusable template logic
- Context providers for application-wide state management
- Progressive enhancement for forms and interactive features
- Server-side rendering with client-side hydration for optimal performance