79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Agent Guidelines for freno-dev
|
|
|
|
## Build/Lint/Test Commands
|
|
- **Dev**: `bun dev` (starts Vinxi dev server)
|
|
- **Build**: `bun build` (production build)
|
|
- **Start**: `bun start` (production server)
|
|
- **No tests configured** - No test runner or test scripts exist yet
|
|
|
|
## Tech Stack
|
|
- **Framework**: SolidJS with SolidStart (Vinxi)
|
|
- **Routing**: @solidjs/router
|
|
- **API**: tRPC v10 with Zod validation
|
|
- **Database**: libSQL/Turso with SQL queries
|
|
- **Styling**: TailwindCSS v4
|
|
- **Runtime**: Bun (Node >=22)
|
|
- **Deployment**: Vercel preset
|
|
|
|
## Code Style
|
|
|
|
### Naming Conventions
|
|
- **Files/Components**: PascalCase (e.g., `Button.tsx`, `UserProfile.tsx`)
|
|
- **Variables/Functions**: camelCase (e.g., `getUserID`, `displayName`)
|
|
- **Types/Interfaces**: PascalCase (e.g., `User`, `ButtonProps`)
|
|
- **Constants**: camelCase or UPPER_SNAKE_CASE for true constants
|
|
|
|
### Imports
|
|
- Prefer named imports from solid-js: `import { createSignal, Show, For } from "solid-js"`
|
|
- Use `~/*` path alias for src imports: `import { api } from "~/lib/api"`
|
|
- Group imports: external deps → solid-js → local (~/)
|
|
|
|
### SolidJS Patterns (NOT React!)
|
|
- **State**: Use `createSignal()` not `useState`. Always call signals: `count()` to read
|
|
- **Effects**: Use `createEffect()` not `useEffect`. Auto-tracks dependencies (no array)
|
|
- **Conditionals**: Prefer `<Show when={condition()}>` over `&&` or ternary
|
|
- **Lists**: Prefer `<For each={items()}>` over `.map()`
|
|
- **Forms**: Use `onInput` (not `onChange`), access `e.currentTarget.value`
|
|
- **Refs**: Use `let ref` binding or `createSignal()` for reactive refs
|
|
|
|
### TypeScript
|
|
- **Strict mode enabled** - always type function params and returns
|
|
- Use interfaces for props: `export interface ButtonProps extends JSX.HTMLAttributes<T>`
|
|
- Use `splitProps()` for component prop destructuring
|
|
- Prefer explicit types over `any` - use `unknown` if type truly unknown
|
|
- Database types: Cast with `as unknown as User` for SQL results
|
|
|
|
### API/Server Patterns
|
|
- **tRPC routers**: Export from `src/server/api/routers/*.ts`
|
|
- **Procedures**: Use `.query()` for reads, `.mutation()` for writes
|
|
- **Validation**: Use Zod schemas in `.input()` - validate all user input
|
|
- **Auth**: Extract userId with `await getUserID(ctx.event.nativeEvent)`
|
|
- **Errors**: Throw `TRPCError` with proper codes (UNAUTHORIZED, NOT_FOUND, BAD_REQUEST)
|
|
- **Database**: Use `ConnectionFactory()` singleton, parameterized queries only
|
|
|
|
### Error Handling
|
|
- Use TRPCError with semantic codes on server
|
|
- Validate inputs with Zod schemas before processing
|
|
- Check auth state before mutations: throw UNAUTHORIZED if missing userId
|
|
- Return structured responses: `{ success: boolean, message?: string }`
|
|
|
|
### Comments
|
|
- **Minimal comments** - prefer self-documenting code
|
|
- JSDoc for exported functions/components only
|
|
- Inline comments for non-obvious logic only
|
|
|
|
### File Organization
|
|
- Routes in `src/routes/` (file-based routing)
|
|
- Components in `src/components/` (reusable) or co-located with routes
|
|
- API routers in `src/server/api/routers/`
|
|
- Types in `src/types/` (shared types) or co-located
|
|
- Utils in `src/lib/` or `src/server/utils.ts`
|
|
|
|
## Key Differences from React
|
|
See `src/lib/SOLID-PATTERNS.md` for comprehensive React→Solid conversion guide. Key gotchas:
|
|
- Signals must be called with `()` to read value
|
|
- `onChange` → `onInput` for real-time input updates
|
|
- `useEffect` → `createEffect` (auto-tracking, no deps array)
|
|
- `Link` → `A` component from @solidjs/router
|
|
- Server actions → tRPC procedures
|