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.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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.
// ✅ 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 entirelyfunctionprocess(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"interfaceUser {
id: string;
name: string;
firstName?: string; // New field, name kept for compatibilitylastName?: string;
}
// ✅ GOOD: Clean break, update all usagesinterfaceUser {
id: string;
firstName: string;
lastName: string;
}
// Then update ALL code that uses User.name
Migration Strategy
Find all usages — grep -r "oldName" src/
Update all at once — Single commit, no transition period
Delete old code — No deprecation warnings, just remove
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.tsimport { OpenAI } from'openai';
// Connect to LiteLLM proxy using OpenAI SDKconst llm = newOpenAI({
baseURL: process.env.LITELLM_URL || 'http://localhost:4000',
apiKey: process.env.LITELLM_API_KEY || 'sk-1234', // Proxy API key
});
exportasyncfunctioncomplete(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 everywhereimportAnthropicfrom'@anthropic-ai/sdk';
importOpenAIfrom'openai';
import { GoogleGenerativeAI } from'@google/generative-ai';
// ❌ BAD: Provider-specific code scattered across codebaseif (provider === 'anthropic') { ... }
elseif (provider === 'openai') { ... }
// ✅ GOOD: Single LiteLLM adapter, switch models via configconst 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
TypeScript (latest)
Validation
Zod (latest)
Testing
Bun test / Vitest
Build
bun build / tsup
Linting
Biome (latest)
Version Strategy
Always use latest. Never pin versions in templates.
