33## Build, Lint, and Test Commands
44
55### Development
6+
67- ` npm run dev ` - Start Next.js dev server with Turbopack (port 3000)
78- ` just frontend ` - Start frontend dev server (from root)
89- ` npm run build ` - Production build
910- ` npm start ` - Start production server
1011
1112### Formatting & Linting
13+
1214- ` npm run format ` - Format all files with Prettier
1315- ` npm run lint ` - Run ESLint
1416- ` npm run lint:fix ` - Auto-fix ESLint issues
2931## Code Style Guidelines
3032
3133### Component Structure
34+
3235``` tsx
3336" use client" ; // Only when needed
34-
35- import React from " react" ;
3637import { Button } from " @/components/ui/button" ;
38+ import React from " react" ;
3739
3840interface Props {
3941 // prop types
@@ -48,6 +50,7 @@ export default function ComponentName({ ...props }: Props) {
4850```
4951
5052### Naming Conventions
53+
5154- ** Files** : PascalCase (e.g., ` UserProfile.tsx ` , ` useTransactions.ts ` )
5255- ** Components** : PascalCase (e.g., ` UserProfile ` , ` TransactionTable ` )
5356- ** Hooks** : camelCase with ` use ` prefix (e.g., ` useTransactions ` , ` useSession ` )
@@ -57,6 +60,7 @@ export default function ComponentName({ ...props }: Props) {
5760- ** Event Handlers** : ` handle ` prefix (e.g., ` handleClick ` , ` handleSubmit ` )
5861
5962### TypeScript Best Practices
63+
6064- Use interfaces for object shapes, types for unions/primitives
6165- Avoid enums - use const objects instead
6266- Use ` satisfies ` operator for type validation
@@ -65,19 +69,22 @@ export default function ComponentName({ ...props }: Props) {
6569- Use ` unknown ` over ` any ` when type is uncertain
6670
6771### React 19 Patterns
72+
6873- Use Server Components by default (no ` "use client" ` )
6974- Minimize client directives - only add when needed
7075- Use ` useActionState ` instead of deprecated ` useFormState `
7176- Use enhanced ` useFormStatus ` with new properties (data, method, action)
7277- Use Suspense boundaries for async components
7378
7479### State Management
80+
7581- ** Server State** : TanStack Query with hooks in ` components/hooks/ `
7682- ** URL State** : Manage via Next.js ` useSearchParams ` and ` router.push() `
7783- ** Local State** : React ` useState ` , ` useReducer ` for small UI state
7884- ** Global State** : React Context for session, theme (suspense-aware)
7985
8086### Component Architecture
87+
8188```
8289components/
8390├── ui/ # Shadcn UI components (no business logic)
@@ -98,65 +105,75 @@ lib/
98105```
99106
100107### Imports
108+
101109- Group and sort imports alphabetically
102110- Use ` @/ ` alias for absolute imports
103111- Order: external, internal components, internal hooks, internal lib
112+
104113``` tsx
105- import { Button } from " @/components/ui/button" ;
106114import { useTransactions } from " @/components/hooks/useTransactions" ;
115+ import { Button } from " @/components/ui/button" ;
107116import { formatCurrency } from " @/lib/utils" ;
108117```
109118
110119### API Layer
120+
111121- Use ` lib/api/request.ts ` ` apiRequest() ` for all fetch calls
112122- API functions in ` lib/api/ ` correspond to backend endpoints
113123- Return ` { data: T } ` pattern from API functions
114124- Use custom error handlers for specific status codes
115125- Always include credentials for cookies
116126
117127### Data Fetching (TanStack Query)
128+
118129- Create hooks in ` components/hooks/ ` (e.g., ` useTransactions.ts ` )
119130- Use ` queryKeys ` object from ` lib/query-client.ts ` for cache keys
120131- Implement optimistic updates for mutations
121132- Use ` enabled ` to prevent unnecessary requests
122133- Set appropriate ` staleTime ` for caching
123134
124135### Styling
136+
125137- Use Shadcn UI components - do not create custom UI components
126138- Tailwind classes via ` cn() ` utility for conditional classes
127139- Follow design tokens (primary, secondary, accent, destructive)
128140- Use responsive prefixes (md:, lg:) for breakpoints
129141- Dark mode via ` next-themes ` - use ` dark: ` prefix
130142
131143### Error Handling
144+
132145- Use ` ApiErrorType ` from ` lib/types/errors.ts `
133146- ` getErrorMessage() ` for user-friendly error messages
134147- Toast notifications via ` sonner ` for user feedback
135148- Console.error for debugging only
136149- Handle API errors in request layer, show toasts at component level
137150
138151### Form Handling
152+
139153- Use native HTML5 validation
140154- React Hook Form for complex forms
141155- Zod schemas for validation (via validator)
142156- ` useFormStatus ` for form submission state
143157- Show loading states during mutations
144158
145159### File Organization
160+
146161- Page routes in ` app/ ` directory
147162- Reusable components in ` components/ `
148163- Shared utilities in ` lib/ `
149164- Models/interfaces in ` lib/models/ `
150165- Constants in ` lib/constants/ `
151166
152167### Performance
168+
153169- Use React.lazy for code splitting
154170- Implement proper loading states
155171- Use virtualization for long lists (` @tanstack/react-virtual ` )
156172- Optimize images with Next.js Image component
157173- Debounce search inputs
158174
159175### Accessibility
176+
160177- Use semantic HTML
161178- ARIA labels on interactive elements
162179- Keyboard navigation support
@@ -166,6 +183,7 @@ import { formatCurrency } from "@/lib/utils";
166183## Testing
167184
168185No test framework is currently configured. Consider adding:
186+
169187- Vitest for unit tests
170188- Testing Library for component tests
171189- Playwright for E2E tests
0 commit comments