TypeScript Guidelines

Design Principles

Code Style

• Naming: Descriptive yet concise names for variables, functions, and classes
• Documentation: JSDoc comments for public APIs, complex logic, and non-obvious design decisions
• Type annotations: Be explicit with typing to reduce inference time; avoid

  any

  unless necessary
• Imports: Avoid barrel exports to prevent circular dependencies; prefer direct imports

Type Safety

• Strict TypeScript: Use strict mode with proper type definitions. Use type-safe patterns like Zod schemas for validation and type-safe DOM helpers where applicable.
• Avoid

  any

  : Use

  unknown

  instead of

  any

  when the type is truly unknown. Narrow types appropriately.
• Type inference: Be explicit with typing to reduce inference time and improve clarity

Type Patterns

• Union types: Use union types for values that can be one of several types
• Discriminated unions: Use discriminated unions for type-safe state machines
• Generic constraints: Use generic constraints to ensure type safety
• Utility types: Leverage TypeScript utility types (Pick, Omit, Partial, etc.)

Architecture

Module Organization

• Each module focuses on one concern with clear boundaries
• Extract reusable functions to avoid duplication
• Design for reusability across contexts
• Co-locate types with their usage or in dedicated type files
• Keep types at appropriate module boundaries

Dependency Management

• Use dependency injection for testability
• Prefer composition over inheritance
• Keep dependencies minimal and focused

Testing

Structure

• Tests mirror

  src/

  directory structure
• Test files:

  *.test.ts

  or

  *.spec.ts

• Use descriptive test names
• Always check for appropriate unit tests when changing code

Quality

• Use AAA (Arrange, Act, Assert) pattern
• Tests should be useful, readable, concise, maintainable
• Test edge cases and error conditions
• Maintain test coverage for critical paths

Tools

• Vitest: Use Vitest for unit and integration tests (preferred over Jest)
• Use

  @vitest/coverage-v8

  for coverage
• Use

  jsdom

  for DOM testing when needed
• Mock external dependencies appropriately
• Playwright: Use Playwright for end-to-end (E2E) tests

Code Formatting and Linting

Prettier

• Use Prettier for consistent code formatting
• Config:

  printWidth: 120

  ,

  singleQuote: true

  ,

  jsxSingleQuote: true

• Run

  pnpm format

  to format code
• Run

  pnpm format:check

  to check formatting

ESLint

• Use ESLint with TypeScript plugin
• Use

  @typescript-eslint/parser

  and

  @typescript-eslint/eslint-plugin

• Run

  pnpm lint

  to check linting
• Run

  pnpm lint:fix

  to auto-fix issues

Framework Recommendations

For Non-Heavy Client Interaction

• Astro: Excellent choice for content-focused sites, blogs, documentation
  • Minimal JavaScript by default
  • Static generation with server islands when needed
  • Great performance and SEO
  • TypeScript-first with excellent DX

For Heavy Client Interaction

• React, Svelte, or SolidJS with TypeScript
• Choose based on team preference and project requirements

Build Tools

• Vite: Preferred build tool for development and production (unless directed otherwise)
• Modern Rust-based tooling: Prefer Rolldown or other lower-level language tooling
  • Avoid Webpack and other older JavaScript-based bundlers unless specifically required

Package Management

• pnpm: Preferred package manager (faster, more efficient than npm/yarn)
• Use

  packageManager

  field in package.json
• Use pnpm workspaces for monorepos

Implementation

• Ensure code passes type checking before committing
• Group related changes with tests in atomic commits
• Check for existing workflow patterns (spec-first, TDD, etc.) and follow them

References

references/pnpm-monorepo.md