# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A SvelteKit (Svelte 5) + Tailwind CSS v4 + Drizzle ORM + Vitest project.

Stack: SvelteKit (Svelte 5), Tailwind CSS v4, Drizzle ORM, Vitest.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npm run check`
- Generate migration: `npx drizzle-kit generate`
- Apply migrations: `npx drizzle-kit migrate`
- Unit tests: `npx vitest run`

## Project structure

- Routes in `src/routes/` (`+page.svelte`, `+page.server.ts`, `+layout.svelte`, `+server.ts`).
- Shared code in `src/lib/` (import as `$lib/...`), server-only code in `src/lib/server/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## SvelteKit (Svelte 5)

- Use Svelte 5 runes: `$state`, `$derived`, `$effect`, `$props`. Do not use legacy `export let` or `$:` syntax in new code.
- Prefer `$derived` over `$effect` for computed values. Use `$effect` only for real side effects.
- Load data in `+page.server.ts` / `+layout.server.ts` `load` functions, not in `onMount`.
- Handle form submissions with form actions and `use:enhance`.
- Read secrets from `$env/static/private` or `$env/dynamic/private`, only in server files.
- Use `error()` and `redirect()` from `@sveltejs/kit` for control flow in load functions and actions.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Drizzle ORM

- Schema lives in TypeScript (`db/schema.ts`). Generate SQL migrations with `drizzle-kit generate` and commit them.
- `drizzle-kit push` is for local prototyping only, never for production databases.
- Infer types with `typeof table.$inferSelect` / `$inferInsert` instead of duplicating interfaces.
- Use the query builder or `sql` template tag; never build SQL with string concatenation.
- Use `db.transaction()` for multi-step writes.

## Vitest

- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.

## Reference docs

- [SvelteKit docs](https://svelte.dev/docs/kit)
- [Svelte 5 runes](https://svelte.dev/docs/svelte/what-are-runes)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Drizzle docs](https://orm.drizzle.team/docs/overview)
- [Vitest docs](https://vitest.dev)