Sveltekit/AGENTS.md

Agent Guidelines

Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type checking
npm run check

# Type checking with watch mode
npm run check:watch

# Sync SvelteKit
npm run prepare

Note: No test framework is configured. Add Vitest or similar for testing.

Code Style Guidelines

File Structure

• src/routes/ - Route pages and layouts
• src/lib/ - Reusable components and utilities (importable via $lib alias)
• src/app.d.ts - Global TypeScript declarations for SvelteKit types
• static/ - Static assets served at /

Svelte Components

Svelte 5 Runes Syntax:

<script lang="ts">
	let { children } = $props();
</script>

Use Svelte 5 runes API for reactivity:

• $props() for component props
• $state() for reactive state
• $derived() for derived values

Imports:

<script lang="ts">
	import favicon from '$lib/assets/favicon.svg';
</script>

Use $lib alias for imports from src/lib/.

TypeScript

Configuration:

• Strict mode enabled
• ES modules ("type": "module")
• Module resolution: bundler

Types:

• Extend global App namespace in app.d.ts for custom interfaces:
  • App.Error
  • App.Locals
  • App.PageData
  • App.PageState
  • App.Platform

Styling

• Use tabs for indentation
• Single quotes for string literals
• Semicolons at end of statements
• No ESLint/Prettier configured - follow SvelteKit conventions

File Naming

• Routes: +page.svelte, +layout.svelte, +error.svelte
• Server endpoints: +page.server.ts, +layout.server.ts, +server.ts
• Load functions: +page.ts, +layout.ts

SvelteKit File Types

Page Files:

• +page.svelte - The component for a route page, renders HTML and handles UI
• +page.ts - Universal load function that runs on server and client, returns data for the page
• +page.server.ts - Server-only load function with access to cookies, database, and server APIs

Layout Files:

• +layout.svelte - Wraps child routes with shared UI (navbar, footer, etc.)
• +layout.ts - Universal load function that provides data to all child routes
• +layout.server.ts - Server-only layout load for shared data (auth session, user info, etc.)

Special Files:

• +error.svelte - Custom error page component, renders when error() is thrown or page fails to load
• +loading.svelte - Loading indicator shown during navigation while data is loading
• +not-found.svelte - Custom 404 page when a route doesn't exist

Server Endpoints:

• +server.ts - API endpoint (GET, POST, PUT, DELETE, etc.) that creates RESTful routes
• Supports named export functions like GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

Root Files:

• src/app.html - HTML template for the entire application, injected with rendered content
• src/app.d.ts - TypeScript declarations extending SvelteKit's global types
• src/hooks.server.ts - Server-side hooks (handle, handleError) for auth, cookies, middleware
• src/hooks.client.ts - Client-side hooks for browser-specific initialization

Import Style

• Group imports: third-party, internal, relative
• Use absolute imports with $lib alias for library imports
• Use relative imports ./ and ../ for same-directory files

Component Conventions

• Always specify lang="ts" in <script> tags
• Use <svelte:head> for document head elements
• Render slot content with {@render children()} for layouts

Error Handling

Use SvelteKit's error handling:

• Throw error(status, message) from load functions
• Create +error.svelte pages for error UI
• Define App.Error interface for custom error types

Development Workflow

1. Run npm run dev for hot-reload development
2. Run npm run check before committing to ensure type safety
3. Test with npm run build before deploying

Adding Tests

No test framework is currently configured. To add testing:

1. Install Vitest: npm install -D vitest @testing-library/svelte
2. Create test files alongside source with .test.ts suffix
3. Update package.json with test scripts