shancheas
ff6814d038
- Introduced coding standards for TypeScript and React in SKILL.md. - Added continuous learning skill with configuration and evaluation scripts. - Created detail layout guidelines for read-only pages. - Established form layout rules for data-entry forms. - Documented project guidelines for the frontend monorepo. - Implemented security review checklist for frontend/Electron applications. - Developed a verification loop skill for comprehensive session checks. This commit enhances the skill set available for developers, ensuring adherence to best practices and improving code quality.
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
---
|
||
name: coding-standards
|
||
description: Coding standards for TypeScript and React in this pnpm monorepo. Use for style, immutability, React, and @repo/* import conventions.
|
||
---
|
||
|
||
# Coding Standards & Best Practices
|
||
|
||
Standards for this TypeScript/React frontend. Not a NestJS API.
|
||
|
||
## Code Quality Principles
|
||
|
||
### 1. Readability First
|
||
|
||
- Code is read more than written
|
||
- Clear variable and function names
|
||
- Self-documenting code over comments
|
||
- Consistent formatting
|
||
|
||
### 2. KISS
|
||
|
||
- Simplest solution that works
|
||
- No premature optimization
|
||
- Easy to understand over clever code
|
||
|
||
### 3. DRY
|
||
|
||
- Extract shared logic into functions or `@repo/ui` / `src/core/`
|
||
- Do not copy-paste modules; copy `example/full-page` then change names
|
||
|
||
### 4. YAGNI
|
||
|
||
- Do not promote to `packages/` until a second app needs it
|
||
- Start in the module; lift to `src/core/` when a second module needs it
|
||
|
||
## TypeScript
|
||
|
||
### Naming
|
||
|
||
```typescript
|
||
const searchQuery = 'widget'
|
||
const isAuthenticated = true
|
||
|
||
async function fetchVehicleType(id: string) {}
|
||
function isValidCode(code: string): boolean {}
|
||
```
|
||
|
||
### Immutability (CRITICAL)
|
||
|
||
```typescript
|
||
const updated = { ...row, name: 'New' }
|
||
const nextItems = [...items, newItem]
|
||
```
|
||
|
||
Never mutate: no `push`, `splice`, or in-place property assignment on shared state.
|
||
|
||
### Errors
|
||
|
||
Handle failures; do not swallow. User-facing text via i18n, not raw `error.message` from HTTP.
|
||
|
||
### Types
|
||
|
||
No `any`. Prefer entity types in `domain/entities` and DTOs next to transformers.
|
||
|
||
## React
|
||
|
||
- Functional components with typed props
|
||
- State updates via functional `setState(prev => …)`
|
||
- Avoid nested ternaries; split into early returns
|
||
- Lazy-load module routes from the presentation factory
|
||
|
||
## Imports (this repo)
|
||
|
||
```ts
|
||
import { Button, Text } from '@repo/ui/components'
|
||
import { FieldTextInput } from '@repo/ui/form'
|
||
import { EnterpriseModuleProvider } from '@repo/ui/foundations'
|
||
import { compose, required } from '@repo/ui/validators'
|
||
import { createHttpClient } from '@repo/core-api/http-client'
|
||
import { CommonRemoteDataServices } from '@repo/core-api/data-services'
|
||
```
|
||
|
||
Do not import `@mantine/core` or axios in `apps/web` feature code.
|
||
|
||
## Validation
|
||
|
||
Zod + `@repo/ui/validators` (`compose`, `required`, `rangeLength`). No class-validator DTOs.
|
||
|
||
## File layout
|
||
|
||
- Web features: `apps/web/src/apps/main/modules/<group>/<feature>/` with `data/`, `domain/`, `presentation/`
|
||
- Shared in one app: `apps/web/src/core/`
|
||
- Shared across apps: `packages/`
|
||
|
||
Files: 200–400 lines typical, 800 max. Functions under ~50 lines.
|
||
|
||
## Performance
|
||
|
||
- `useMemo` / `useCallback` only when measured or lists are large
|
||
- Lazy-load heavy pages
|
||
- No N+1 UI fetches; use the module data service list endpoint
|
||
|
||
## Testing
|
||
|
||
Vitest AAA pattern. Descriptive names. See `tdd-workflow`.
|
||
|
||
## Code smells
|
||
|
||
- Functions > 50 lines — split
|
||
- Nesting > 4 — early return
|
||
- Magic numbers — named constants
|
||
- `console.log` in production
|
||
- Raw Mantine, raw axios, `import.meta.env` in components
|