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.

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