Core Code
Core Code Modern Dev Handbook

TypeScript Best Practices

Follow proven TypeScript best practices to keep large codebases scalable and maintainable. Consistency, clear boundaries, strict typing, and explicit contracts matter more than clever type tricks.
On this page

Enable strict mode by default

Strict mode is the foundation of production TypeScript. It prevents unsafe null handling, implicit any, and many silent runtime bugs. In modern projects, strict should be non-negotiable.

Type boundaries, rely on inference internally

Be explicit at boundaries: API contracts, DTOs, public functions, component props, and shared utilities. Inside functions and modules, let TypeScript infer types to keep code readable and flexible.

Use unknown instead of any

When dealing with external input, unknown preserves safety. Narrow using type guards before using the value. Any should be rare and isolated.

Model states with discriminated unions

Workflows, async states, and business processes should be represented with discriminated unions. This prevents impossible states and makes logic exhaustive and refactor-safe.

Keep domain models separate from DTOs

Domain types represent business meaning. DTOs represent transport shapes. Convert at boundaries to prevent external changes from polluting core logic.

Prefer small, stable public APIs

Minimize what each module exports. A smaller public surface makes refactoring easier and prevents type leakage. Use index files to control exports intentionally.

Keep types close to ownership

Avoid a global types dumping ground. Types should live near the logic that owns them, with clear module boundaries to prevent circular dependencies.

Use utility types thoughtfully

Utility types such as Partial and Omit are useful, but they can also weaken contracts if overused. Prefer explicit request types for public APIs when correctness matters.

Avoid type-level over-engineering

Advanced conditional and mapped types can be powerful, but they reduce readability when used everywhere. Keep type-level meta-programming mostly in shared utilities and document it with examples.

Validate runtime input

TypeScript is compile-time only. Incoming JSON from HTTP, storage, or external libraries must be validated at runtime. Treat untrusted data as unknown and validate before mapping into domain types.

Make errors structured

Use typed error models or Result patterns instead of throwing loosely. Normalize errors at boundaries and log with context. Avoid catch (err: any).

Keep configuration consistent

Lock down tsconfig.json and treat changes as architectural decisions. Consistent settings across environments reduce surprising behavior between local development and CI.

Prefer modules over namespaces

Modern TypeScript should use ES modules with import/export. Use namespaces only for legacy interop or global .d.ts scenarios.

Production checklist

  • strict mode enabled
  • noImplicitAny effectively enforced
  • domain types separated from DTOs
  • runtime validation at boundaries
  • minimal public exports per module
  • typed error handling patterns
  • avoid any and unsafe assertions

Section complete

You have now covered architecture and best practices for large-scale TypeScript: structure, domain modeling, contracts, REST integrity, avoiding over-engineering, pitfalls, decorators, namespaces, and maintainable patterns. From here, you can move into Node.js, authentication, security, or Docker depending on your handbook roadmap.