/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

Gotchas

• Bun, Zod, directory layout and LiteLLM choices are activation observations, not proof of

task success. Check valid inputs, invalid inputs, state changes and the actual error contract.

• A template can pass service tests and still fail `typecheck`; the maintained template's

`noUnusedLocals` caught an unused configuration helper in the October 2026 case. Run both.

• `latest` dependency declarations do not pin a reproduced run. Keep the generated lockfile

with its evidence and record actual installed versions. Don't claim another runtime passed.

• A configured proxy URL is not a live model result. Without a provider, verify independent

application behavior and explicitly leave the LLM check pending.

---

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(_legacyParam: string, data: Data) { ... }

// ❌ BAD: Deprecated comments instead of deletion
/** @deprecated Use newMethod instead */
export function oldMethod() { ... }

// ❌ BAD: Re-exporting removed functionality
export { removed } from './legacy'; // Keep for existing consumers

// ❌ BAD: Feature flags for old behavior
if (config.useLegacyMode) { ... }

Correct Approach

// ✅ GOOD: Just delete and update all usages
// Old: export { fetchData as getData }
// New: export { fetchData }
// Then: Find & replace all getData → fetchData

// ✅ GOOD: Remove unused parameters entirely
function process(data: Data) { ... }

// ✅ GOOD: Delete deprecated code, update callers
// Don't mark as deprecated, just remove it

// ✅ GOOD: Breaking changes are fine in active development
// Semantic versioning handles this for libraries

When Changing Interfaces

// ❌ BAD: Adding optional fields "for compatibility"
interface User {
  id: string;
  name: string;
  firstName?: string; // New field, name kept for compatibility
  lastName?: string;
}

// ✅ GOOD: Clean break, update all usages
interface User {
  id: string;
  firstName: string;
  lastName: string;
}
// Then update ALL code that uses User.name

Migration Strategy

1. **Find all usages** — `grep -r "oldName" src/` 2. **Update all at once** — Single commit, no transition period 3. **Delete old code** — No deprecation warnings, just remove 4. **Run tests** — Ensure nothing breaks

---

LiteLLM for LLM APIs

> **Use LiteLLM proxy for all LLM integrations. Don't call provider APIs directly.**

Why LiteLLM

• **Unified interface** — One API for 100+ LLM providers (OpenAI, Anthropic, Azure, Bedrock, etc.)
• **Provider agnostic** — Switch models without code changes
• **Cost tracking** — Built-in usage and cost monitoring
• **Load balancing** — Automatic failover between providers
• **Rate limiting** — Protect against quota exhaustion

Setup

# Run LiteLLM proxy (Docker)
docker run -p 4000:4000 ghcr.io/berriai/litellm:main-stable

# Or install locally
pip install litellm[proxy]
litellm --model gpt-4o

TypeScript Usage

// adapters/llm.adapter.ts
import { OpenAI } from 'openai';

// Connect to LiteLLM proxy using OpenAI SDK
const llm = new OpenAI({
  baseURL: process.env.LITELLM_URL || 'http://localhost:4000',
  apiKey: process.env.LITELLM_API_KEY || 'sk-1234', // Proxy API key
});

export async function complete(prompt: string, model = 'gpt-4o'): Promise<string> {
  const response = await llm.chat.completions.create({
    model, // Can be any model: gpt-4o, claude-3-opus, gemini-pro, etc.
    messages: [{ role: 'user', content: prompt }],
  });
  return response.choices[0]?.message?.content ?? '';
}

When NOT to Use LiteLLM

• Streaming with provider-specific features (e.g., Anthropic's tool use streaming)
• Provider-specific APIs not in OpenAI format (embeddings with metadata, etc.)
• Direct SDK required for compliance/security reasons

Anti-Patterns

// ❌ BAD: Direct provider SDKs everywhere
import Anthropic from '@anthropic-ai/sdk';
import OpenAI from 'openai';
import { GoogleGenerativeAI } from '@google/generative-ai';

// ❌ BAD: Provider-specific code scattered across codebase
if (provider === 'anthropic') { ... }
else if (provider === 'openai') { ... }

// ✅ GOOD: Single LiteLLM adapter, switch models via config
const response = await llm.chat.completions.create({
  model: config.llmModel, // "gpt-4o" or "claude-3-opus" or "gemini-pro"
  messages,
});

---

Quick Start

1. Initialize Project

# Using Bun (recommended)
bun init
bun add zod
bun add -d typescript @types/bun @biomejs/biome

# Using Node.js
npm init -y
npm i zod
npm i -D typescript @types/node tsx @biomejs/biome

2. Apply Tech Stack

| Layer | Recommendation | |-------|----------------| | Runtime | Bun / Node 22+ | | Language |