33## Development Commands
44
55``` bash
6- # Package manager: pnpm is required (enforced via preinstall script)
7- pnpm install # Install dependencies
8- pnpm dev # Start development server with Turbopack
9- pnpm build # Build for production
10- pnpm start # Start production server on port 1030
11- pnpm stage # Start staging server on port 1031
6+ # Package manager: bun
7+ bun install # Install dependencies
8+ bun run dev # Start development server with Turbopack
9+ bun run build # Build for production
10+ bun run start # Start production server on port 1030
11+ bun run stage # Start staging server on port 1031
1212
1313# Quality assurance
14- pnpm lint # Run ESLint
15- pnpm lint:fix # Auto-fix ESLint issues
16- pnpm type-check # Run TypeScript type checking
14+ bun run check # Run Linter, Formatter, Unit Tests and Type Checker concurrently
15+ bun run lint:fix # Auto-fix Biome issues
16+ bun run type-check # Run TypeScript type checking
1717
1818# Testing
19- pnpm test # Run Jest unit tests
20- pnpm test:watch # Run Jest in watch mode
21- pnpm test:coverage # Run tests with coverage report
22- pnpm test:e2e # Run Playwright end-to-end tests
19+ bun run test:e2e # Run Playwright end-to-end tests
2320```
2421
2522## Project Architecture
@@ -31,8 +28,8 @@ pnpm test:e2e # Run Playwright end-to-end tests
3128- ** Styling** : SCSS with modular structure
3229- ** Internationalization** : next-intl for multi-language support
3330- ** Performance** : Million.js compiler optimization
34- - ** Testing** : Jest for unit tests, Playwright for E2E
35- - ** Package Manager** : pnpm (enforced)
31+ - ** Testing** : Bun test runner for unit tests, Playwright for E2E
32+ - ** Package Manager** : bun
3633
3734### Key Directory Structure
3835
7774
7875### Code Quality Requirements
7976
80- - All utility functions must have 100% test coverage using Jest
77+ - All utility functions must have 100% test coverage using Bun test runner
8178- TypeScript is mandatory with proper type definitions in models/ folders
8279- Follow conventional commits specification for commit messages
83- - Use ESLint configuration (includes Next.js and custom rules)
80+ - Use Biome for linting and formatting
8481
8582### Testing Strategy
8683
@@ -101,3 +98,128 @@ src/
10198- Add translations to ALL language files in locales/ when adding new strings
10299- Use next-intl translation keys consistently
103100- Follow existing key structure conventions
101+
102+
103+ # Ultracite Code Standards
104+
105+ This project uses ** Ultracite** , a zero-config preset that enforces strict code quality standards through automated formatting and linting.
106+
107+ ## Quick Reference
108+
109+ - ** Format code** : ` bun x ultracite fix `
110+ - ** Check for issues** : ` bun x ultracite check `
111+ - ** Diagnose setup** : ` bun x ultracite doctor `
112+
113+ Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
114+
115+ ---
116+
117+ ## Core Principles
118+
119+ Write code that is ** accessible, performant, type-safe, and maintainable** . Focus on clarity and explicit intent over brevity.
120+
121+ ### Type Safety & Explicitness
122+
123+ - Use explicit types for function parameters and return values when they enhance clarity
124+ - Prefer ` unknown ` over ` any ` when the type is genuinely unknown
125+ - Use const assertions (` as const ` ) for immutable values and literal types
126+ - Leverage TypeScript's type narrowing instead of type assertions
127+ - Use meaningful variable names instead of magic numbers - extract constants with descriptive names
128+
129+ ### Modern JavaScript/TypeScript
130+
131+ - Use arrow functions for callbacks and short functions
132+ - Prefer ` for...of ` loops over ` .forEach() ` and indexed ` for ` loops
133+ - Use optional chaining (` ?. ` ) and nullish coalescing (` ?? ` ) for safer property access
134+ - Prefer template literals over string concatenation
135+ - Use destructuring for object and array assignments
136+ - Use ` const ` by default, ` let ` only when reassignment is needed, never ` var `
137+
138+ ### Async & Promises
139+
140+ - Always ` await ` promises in async functions - don't forget to use the return value
141+ - Use ` async/await ` syntax instead of promise chains for better readability
142+ - Handle errors appropriately in async code with try-catch blocks
143+ - Don't use async functions as Promise executors
144+
145+ ### React & JSX
146+
147+ - Use function components over class components
148+ - Call hooks at the top level only, never conditionally
149+ - Specify all dependencies in hook dependency arrays correctly
150+ - Use the ` key ` prop for elements in iterables (prefer unique IDs over array indices)
151+ - Nest children between opening and closing tags instead of passing as props
152+ - Don't define components inside other components
153+ - Use semantic HTML and ARIA attributes for accessibility:
154+ - Provide meaningful alt text for images
155+ - Use proper heading hierarchy
156+ - Add labels for form inputs
157+ - Include keyboard event handlers alongside mouse events
158+ - Use semantic elements (` <button> ` , ` <nav> ` , etc.) instead of divs with roles
159+
160+ ### Error Handling & Debugging
161+
162+ - Remove ` console.log ` , ` debugger ` , and ` alert ` statements from production code
163+ - Throw ` Error ` objects with descriptive messages, not strings or other values
164+ - Use ` try-catch ` blocks meaningfully - don't catch errors just to rethrow them
165+ - Prefer early returns over nested conditionals for error cases
166+
167+ ### Code Organization
168+
169+ - Keep functions focused and under reasonable cognitive complexity limits
170+ - Extract complex conditions into well-named boolean variables
171+ - Use early returns to reduce nesting
172+ - Prefer simple conditionals over nested ternary operators
173+ - Group related code together and separate concerns
174+
175+ ### Security
176+
177+ - Add ` rel="noopener" ` when using ` target="_blank" ` on links
178+ - Avoid ` dangerouslySetInnerHTML ` unless absolutely necessary
179+ - Don't use ` eval() ` or assign directly to ` document.cookie `
180+ - Validate and sanitize user input
181+
182+ ### Performance
183+
184+ - Avoid spread syntax in accumulators within loops
185+ - Use top-level regex literals instead of creating them in loops
186+ - Prefer specific imports over namespace imports
187+ - Avoid barrel files (index files that re-export everything)
188+ - Use proper image components (e.g., Next.js ` <Image> ` ) over ` <img> ` tags
189+
190+ ### Framework-Specific Guidance
191+
192+ ** Next.js:**
193+ - Use Next.js ` <Image> ` component for images
194+ - Use ` next/head ` or App Router metadata API for head elements
195+ - Use Server Components for async data fetching instead of async Client Components
196+
197+ ** React 19+:**
198+ - Use ref as a prop instead of ` React.forwardRef `
199+
200+ ** Solid/Svelte/Vue/Qwik:**
201+ - Use ` class ` and ` for ` attributes (not ` className ` or ` htmlFor ` )
202+
203+ ---
204+
205+ ## Testing
206+
207+ - Write assertions inside ` it() ` or ` test() ` blocks
208+ - Avoid done callbacks in async tests - use async/await instead
209+ - Don't use ` .only ` or ` .skip ` in committed code
210+ - Keep test suites reasonably flat - avoid excessive ` describe ` nesting
211+
212+ ## When Biome Can't Help
213+
214+ Biome's linter will catch most issues automatically. Focus your attention on:
215+
216+ 1 . ** Business logic correctness** - Biome can't validate your algorithms
217+ 2 . ** Meaningful naming** - Use descriptive names for functions, variables, and types
218+ 3 . ** Architecture decisions** - Component structure, data flow, and API design
219+ 4 . ** Edge cases** - Handle boundary conditions and error states
220+ 5 . ** User experience** - Accessibility, performance, and usability considerations
221+ 6 . ** Documentation** - Add comments for complex logic, but prefer self-documenting code
222+
223+ ---
224+
225+ Most formatting and common issues are automatically fixed by Biome. Run ` bun x ultracite fix ` before committing to ensure compliance.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
![kodiakhq[bot]](https://avatars.githubusercontent.com/in/29196?v=4&size=40){kind=avatar}
0 commit comments