code-style

# Code style, TypeScript, and naming **When to use:** Biome formatting, import style, strict TypeScript, naming (including React file names), or generated files. For **where** domain code lives, see [architecture-boundaries](../architecture-boundaries/SKILL.md). ## Code style (Biome) Biome config (`biome.json`) is the source of truth: - Indentation: 2 spaces - Max line width: 120 - Strings: double quotes - Semicolons: as needed - Ignore generated/output paths: `dist/**`, `coverage/**`, `.turbo/**`, `node_modules/**`, `**/*.gen.ts`, `**/models.dev.json` - Prefer package-local formatting: `pnpm --filter @app/api format` - Cognitive complexity (`complexity/noExcessiveCognitiveComplexity`) is enabled at max **15**. Keep new and edited functions at or under that score — split nested conditionals, loops, and branches into named helpers rather than silencing the rule. Existing hotspots are warn-only until they are refactored; do not add complexity to them. ## Imports - Prefer static imports; avoid dynamic import patterns unless justified - Use `import type { ... }` for type-only imports - Keep imports explicit and grep-friendly - Preserve clear grouping/order (external, internal alias, then relative) - Avoid wildcard exports/imports when explicit named exports are practical - Avoid barrel files (`index.ts` re-exporting from the same directory); import from the specific module - **Use `.ts`/`.tsx` extensions** in relative imports (not `.js`). The codebase uses TypeScript source extensions for module resolution ## TypeScript Base config: `tsconfig.base.json`. Typechecking runs under **`tsgo`** (TypeScript 7 beta, via `@typescript/native-preview`) — use `tsgo -p tsconfig.json --noEmit` in `typecheck` scripts, never `tsc`. - `strict: true` is enabled; keep code strict-clean - Module system: `NodeNext` + ESM (`"type": "module"` in packages/apps) - For new domain data contracts, define the canonical shared shape as a Zod schema first when runtime validation is required, then infer TypeScript types from that schema or from Drizzle schemas where appropriate. - Treat schemas in `src/entities/<entity>.ts` as the canonical domain contract. Schemas and types elsewhere in the same domain or at app/platform boundaries should derive from or reuse those entity shapes whenever practical instead of restating identical fields. - Canonical entity schemas should treat system-managed fields such as `id`, `createdAt`, and `updatedAt` as core entity fields. Do not split an entity into a business payload plus an appended "persistence" wrapper unless there is a truly distinct boundary/input DTO that needs that separation. - Enum-like contracts should use literal-string unions or `as const` objects, not TypeScript enums. - Use shared domain schemas to validate data crossing from app/platform boundaries into domain use-cases. - If a boundary schema must differ materially from the entity shape, reuse domain constants, field schemas, and literal unions before introducing duplicated inline limits or sentinel values. - Configurable thresholds, weights, debounce windows, sentinel values, and similar tunables should live in named constants inside the owning domain package rather than as scattered inline literals. - Types and schemas that exist only as the inputs of one use-case should stay in that use-case file unless several use-cases truly share the same contract. - Prefer explicit domain types/interfaces over loose objects - Methods/functions with more than one argument should default to a single named-arguments object rather than positional arguments - Use `readonly` fields for immutable domain data shapes - Avoid `any`; use `unknown` + narrowing - Avoid unnecessary type assertions (`as { ... }`); prefer relying on inferred types from libraries - Validate boundary inputs early (API input, queue payloads, external IO) ## General principles - Prefer minimal, explicit abstractions — YAGNI - Comments: default to none, one line when needed — see the repo-wide convention in the root `AGENTS.md`. Only traps (code that looks removable or wrong but isn't), non-obvious external constraints, and sibling-complete contract docs (e.g. port JSDoc) earn a comment; never what-narration or design rationale ## Domain module layout - Canonical entity schemas and inferred entity types belong in `src/entities/<entity>.ts`. - Domain package constants belong in `src/constants.ts`. - Domain package errors belong in `src/errors.ts`. - Small domain-scoped shared helpers such as predicates or lifecycle helpers belong in `src/helpers.ts`. ## Naming conventions - Types/interfaces/classes: `PascalCase` - Variables/functions/methods: `camelCase` - Constants: `UPPER_SNAKE_CASE` only for true constants; otherwise `camelCase` + `as const` - Shared base schemas/types that are extended into discriminated unions or related variants should use `baseXxxSchema` / `BaseXxx` naming rather than `xxxCommonSchema` / `XxxCommon`. - File names favor concise module roots (`src/index.ts`, `src/server.ts`, `src/main.tsx`) - React component files use **kebab-case**: `my-component.tsx` or `my-component/index.tsx` — never `PascalCase` file names (e.g. `MyComponent.tsx`). This matches the `@repo/ui` convention (`table-skeleton.tsx`, `form-field.tsx`, etc.) - Package names follow scoped workspace style (`@app/*`, `@domain/*`, etc.) ## Generated files - `apps/web/src/routeTree.gen.ts` is auto-generated by TanStack Router — do not manually edit - Generated files may be regenerated during builds or dev server runs; commit them when they change but do not modify by hand