GitHub Copilot Instructions

This file contains custom instructions for GitHub Copilot. These instructions are based on the .cursorrules file and provide guidelines for Svelte 5, SvelteKit, and TypeScript development.

You are an expert in Svelte 5, SvelteKit, TypeScript, and modern web development.

Key Principles

• Write concise, technical code with accurate Svelte 5 and SvelteKit examples.
• Leverage SvelteKit's server-side rendering (SSR) and static site generation (SSG) capabilities.
• Prioritize performance optimization and minimal JavaScript for optimal user experience.
• Use descriptive variable names and follow Svelte and SvelteKit conventions.
• Organize files using SvelteKit's file-based routing system.

Code Style and Structure

• Write concise, technical TypeScript or JavaScript code with accurate examples.
• Use functional and declarative programming patterns; avoid unnecessary classes except for state machines.
• Prefer iteration and modularization over code duplication.
• Structure files: types, component logic, markup, styles.
• Follow Svelte's official documentation for setup and configuration: https://svelte.dev/docs/svelte/overview

Naming Conventions

• Use PascalCase for component files (e.g., components/AuthForm.svelte).
• Use PascalCase for component names in imports and usage.
• Use snake_case for variables, functions, and props.
• Use UPPER_CASE for true constants but not general const vars

TypeScript Usage

• Use TypeScript for all code; prefer interfaces over types.
• Avoid enums; use string literals instead and const objects if needed.
• Enable strict mode in TypeScript for better type safety.

Svelte Runes

• $state: Declare reactive state

  let count = $state(0);

• $derived: Compute derived values

  let doubled = $derived(count * 2);

• $effect: Manage side effects and lifecycle

  $effect(() => {
  	console.log(`Count is now ${count}`);
  });

• $props: Declare component props

  let { optionalProp = 42, requiredProp } = $props();

• $bindable: Create two-way bindable props

  let { bindableProp = $bindable() } = $props();

• $inspect: Debug reactive state (development only)

  $inspect(count);

UI and Styling

• Use css vars defined in src/styles/variables.css for css vars.
• Prefer css vars for any property where they exist. Colors specifically cannot be defined without css vars.
• Use Svelte's built-in transition and animation features.
• Use bg and fg convention for background and color properties respecitvely.

SvelteKit Project Structure

• Use the recommended SvelteKit project structure:

  - src/
    - lib/
    - routes/
    - assets/
    - server/
    - actions/
    - state/
    - utilities/
    - app.html
    - env.ts
    - params.ts
  - static/
  - vite.config.ts

• SvelteKit config lives in the sveltekit() plugin in vite.config.ts; there is no svelte.config.js.
• Import with the package.json subpath imports (#lib/*, #server/*, #state/*, #utilities/*, #actions/*, #assets/*, #styles/*, #const) and include the file extension (.js for .ts files).
• Declare environment variables in src/env.ts and import them from $app/env/private or $app/env/public.

Component Development

• Create .svelte files for Svelte components.
• Use .svelte.ts files for state.
• Implement proper component composition and reusability.
• Use Svelte's props for data passing.
• Leverage Svelte's reactive declarations for local state management.

State Management

• Use classes for complex state management (state machines):

  // counter.svelte.ts
  class Counter {
  	count = $state(0);
  	incrementor = $state(1);
  
  	increment() {
  		this.count += this.incrementor;
  	}
  
  	resetCount() {
  		this.count = 0;
  	}
  
  	resetIncrementor() {
  		this.incrementor = 1;
  	}
  }
  
  export const counter = new Counter();

• Use in components:

  <script lang="ts">
  	import { counter } from './counter.svelte.ts';
  </script>
  
  <button onclick={() => counter.increment()}>
  	Count: {counter.count}
  </button>

Routing and Pages

• Utilize SvelteKit's file-based routing system in the src/routes/ directory.
• Implement dynamic routes using [slug] syntax.
• Use load functions for server-side data fetching and pre-rendering.
• Implement proper error handling with +error.svelte pages.

Server-Side Rendering (SSR) and Static Site Generation (SSG)

• Leverage SvelteKit's SSR capabilities for dynamic content.
• Implement SSG for static pages using prerender option.
• Deploys to Vercel with adapter-vercel (Node.js 22 runtime).

Performance Optimization

• Leverage Svelte's compile-time optimizations.
• Use {#key} blocks to force re-rendering of components when needed.
• Implement code splitting using dynamic imports for large applications.
• Profile and monitor performance using browser developer tools.
• Minimize use of client-side JavaScript; leverage SvelteKit's SSR and SSG.
• Use modern html elements and features wherever possible.
• Implement proper lazy loading for images and other assets.

Data Fetching and API Routes

• Use load functions for server-side data fetching.
• Implement proper error handling for data fetching operations.
• Create API routes in the src/routes/api/ directory.
• Implement proper request handling and response formatting in API routes.
• Use SvelteKit's hooks for global API middleware.
• Data comes from Prisma via a Planetscale Mysql database.

SEO and Meta Tags

• Use Svelte:head component for adding meta information.
• Implement canonical URLs for proper SEO.
• Create reusable SEO components for consistent meta tag management.

Forms and Actions

• Utilize SvelteKit's form actions for server-side form handling.
• Implement proper client-side form validation using Svelte's reactive declarations.
• Use progressive enhancement for JavaScript-optional form submissions.

Accessibility

• Ensure proper semantic HTML structure in Svelte components.
• Implement ARIA attributes where necessary.
• Ensure keyboard navigation support for interactive elements.
• Use Svelte's bind:this for managing focus programmatically.

Key Conventions

1. Embrace Svelte's simplicity and avoid over-engineering solutions.
2. Use SvelteKit for full-stack applications with SSR and API routes.
3. Prioritize Web Vitals (LCP, INP, CLS) for performance optimization.
4. Use environment variables for configuration management.
5. Follow Svelte's best practices for component composition and state management.
6. Ensure cross-browser compatibility by testing on multiple platforms.
7. Keep your Svelte and SvelteKit versions up to date.

Documentation

• Svelte Documentation: https://svelte.dev/docs/svelte/overview
• SvelteKit Documentation: https://svelte.dev/docs/kit/introduction
• Prisma Documentation: https://www.prisma.io/docs

Refer to Svelte, SvelteKit, and Prisma documentation for detailed information on components, database queries, and best practices.