152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# Agent Guidelines for placebo.mk
|
|
|
|
## Project Overview
|
|
News site in Macedonia with sarcastic tone. Minimalistic design using TanStack stack.
|
|
|
|
## Tech Stack
|
|
- **Frontend**: TanStack (React 19, Query, Router) + Vite + Tailwind CSS + shadcn/ui
|
|
- **Backend**: NestJS + TypeORM + SQLite
|
|
- **CMS**: Strapi (in /cms)
|
|
|
|
## Build Commands
|
|
|
|
### Backend (NestJS)
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run start:dev # Watch mode
|
|
npm run build
|
|
npm run start:prod
|
|
npm run lint # Lint
|
|
npm run lint:fix # Auto-fix
|
|
npm run type-check # TypeScript check
|
|
npm test # All tests
|
|
npm test app.service.spec.ts # Single file
|
|
npm test -t "should" # By test name
|
|
npm run test:cov # Coverage
|
|
npm run test:e2e # E2E tests
|
|
```
|
|
|
|
### Frontend (TanStack)
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # Vite dev server
|
|
npm run build
|
|
npm run preview
|
|
npm run lint
|
|
npm run lint:fix
|
|
npm run type-check
|
|
npm test # All tests
|
|
npm test Header.test.tsx # Single file
|
|
npm test -t "renders" # By name
|
|
npm run test:ui # Vitest UI
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### Formatting & TypeScript
|
|
- Use Prettier (2 spaces, single quotes, trailing commas, 100 char max)
|
|
- Strict TypeScript - no implicit `any`, avoid `any`, use `unknown`
|
|
- Explicit return types for public methods
|
|
- Prefer interfaces over types for objects
|
|
- Use `readonly` for immutable properties
|
|
|
|
### Naming Conventions
|
|
- **Files**: kebab-case (`user-profile.ts`, `auth.service.ts`)
|
|
- **Classes**: PascalCase (`UserService`, `AuthGuard`)
|
|
- **Functions/Variables**: camelCase (`getUser`, `isLoading`)
|
|
- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRIES`)
|
|
- **Private members**: underscore prefix (`_cache`, `_validate()`)
|
|
- **Interfaces**: PascalCase, no 'I' prefix (`User`, `ApiResponse`)
|
|
|
|
### Import Order
|
|
- External libraries first, then internal modules, then relative imports
|
|
|
|
|
|
### File Structure
|
|
```
|
|
backend/src/
|
|
modules/feature-name/
|
|
feature-name.module.ts
|
|
feature-name.controller.ts
|
|
feature-name.service.ts
|
|
feature-name.entity.ts
|
|
feature-name.dto.ts
|
|
common/{decorators,filters,guards,interceptors,pipes}
|
|
config/
|
|
|
|
frontend/src/
|
|
components/{ui,layout,features}/
|
|
hooks/
|
|
lib/
|
|
queries/
|
|
routes/
|
|
types/
|
|
utils/
|
|
```
|
|
|
|
### Error Handling
|
|
- **Backend**: Use NestJS exceptions (`NotFoundException`, `BadRequestException`), custom exceptions, Logger
|
|
- **Frontend**: Error boundaries, try-catch with user-friendly messages
|
|
|
|
### API Conventions
|
|
- REST endpoints: `/api/v1/resources`
|
|
- JSON fields: snake_case
|
|
- Pagination: `page`, `limit` query params
|
|
- Response format:
|
|
```typescript
|
|
{
|
|
data: T,
|
|
meta: { total, page, limit },
|
|
error?: { code, message }
|
|
}
|
|
```
|
|
|
|
### Testing
|
|
- Unit tests for services/hooks (AAA pattern: Arrange-Act-Assert)
|
|
- Integration tests for API endpoints
|
|
- E2E tests for critical user flows
|
|
- Descriptive test names that explain what is tested
|
|
- Mock external dependencies (use Jest for backend, Vitest for frontend)
|
|
- Run `npm test` for all tests or target specific files/names
|
|
|
|
### Git Workflow
|
|
- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
|
|
- Keep commits atomic and focused
|
|
- Write clear commit messages in imperative mood
|
|
|
|
### Component Guidelines
|
|
- Keep components small and focused (< 200 lines)
|
|
- Use functional components with hooks
|
|
- Prefer composition over inheritance
|
|
- Extract complex logic into custom hooks
|
|
- Use TanStack Query for server state management
|
|
- Use TanStack Router for routing
|
|
- Validate props with TypeScript
|
|
|
|
### Database
|
|
- Use TypeORM for SQLite
|
|
- Define entities with proper relationships
|
|
- Use migrations for schema changes
|
|
- Seed data with factory functions
|
|
- Use TypeORM repositories for data access
|
|
|
|
### UI Components
|
|
- Use shadcn/ui components from `components/ui/`
|
|
- Use class-variance-authority (CVA) for component variants
|
|
- Use clsx and tailwind-merge for class composition
|
|
- Follow shadcn patterns for new component creation
|
|
|
|
|
|
## Environment Variables
|
|
- Backend: `@nestjs/config` with `.env` files
|
|
- Frontend: Vite env vars (`VITE_API_URL`)
|
|
- Never commit secrets to the repository.
|
|
- Example frontend env: `VITE_API_URL=http://localhost:3000`
|
|
- Example backend env: `DATABASE_PATH=./data.db`
|
|
- Store sensitive config in `.env` files
|
|
- Use `DATABASE_PATH` for SQLite location
|
|
|
|
|