144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# Agent Guidelines
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# 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:**
|
|
```svelte
|
|
<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:**
|
|
```svelte
|
|
<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
|