typescript-project

name	typescript-project
description	Modern TypeScript project architecture guide for 2025. Use when creating new TS projects, setting up configurations, or designing project structure. Covers tech stack selection, layered architecture, and best practices.

TypeScript Project Architecture

Core Principles

• Type safety first — Strict mode, no any, Zod for runtime validation
• ESM native — ES Modules by default, Node 22+ / Bun
• Layered architecture — Separate lib/services/adapters
• 200-line limit — No file exceeds 200 lines (see elegant-architecture skill)
• Test reality — Vitest/Bun test, minimal mocks
• No backwards compatibility — Delete, don't deprecate. Change directly, no shims
• LiteLLM for LLM APIs — Use LiteLLM proxy for all LLM integrations, unless specific SDK required

---

No Backwards Compatibility

Delete unused code. Change directly. No compatibility layers.

Why

• Dead code is tech debt
• Compatibility shims add complexity
• Old patterns spread through copy-paste
• "Temporary" workarounds become permanent

Anti-Patterns to Avoid

// ❌ BAD: Renaming but keeping old export
export { newName };
export { newName as oldName }; // "for backwards compatibility"

// ❌ BAD: Unused parameter with underscore
function process() { ... }



  () { ... }


 { removed }  ; 


 (config.) { ... }