Advanced TypeScript patterns and best practices for 2025
Modern TypeScript development patterns for type safety, runtime validation, and optimal configuration.
New Project: Use 2025 tsconfig → Enable strict + noUncheckedIndexedAccess → Choose Zod for validation
Existing Project: Enable strict: false initially → Fix any with unknown → Add noUncheckedIndexedAccess
API Development: Zod schemas at boundaries → z.infer<typeof Schema> for types → satisfies for routes
Library Development: Enable declaration: true → Use const type parameters → See advanced-patterns-2025.md
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"verbatimModuleSyntax": true,
"isolatedModules": true,
"skipLibCheck": true,
"declaration": true,
"declarationMap": true
}
}
| Option | Purpose | When to Enable |
|---|---|---|
noUncheckedIndexedAccess | Forces null checks on array/object access | Always for safety |
exactOptionalPropertyTypes | Distinguishes undefined from missing | APIs with optional fields |
verbatimModuleSyntax | Enforces explicit type-only imports | ESM projects |
erasableSyntaxOnly | Node.js 22+ native TS support | Type stripping environments |
See references/configuration.md for repo-specific tsconfig patterns (CommonJS CLI, NodeNext strict, Next.js bundler).
Preserve literal types through generic functions:
function createConfig<const T extends Record<string, unknown>>(config: T): T {
return config;
}
const config = createConfig({
apiUrl: "https://api.example.com",
timeout: 5000
});
// Type: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000 }
Validate against a type while preserving literal inference:
type Route = { path: string; children?: Routes };
type Routes = Record<string, Route>;
const routes = {
AUTH: { path: "/auth" },
HOME: { path: "/" }
} satisfies Routes;
routes.AUTH.path; // Type: "/auth" (literal preserved)
routes.NONEXISTENT; // ❌ Type error
Type-safe string manipulation and route extraction:
type ExtractParams<T extends string> =
T extends `${string}:${infer Param}/${infer Rest}`
? Param | ExtractParams<Rest>
: T extends `${string}:${infer Param}`
? Param
: never;
type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"
type Result<T, E = Error> =
| { success: true; data: T }
| { success: false; error: E };
function handleResult<T>(result: Result<T>): T {
if (result.success) return result.data;
throw result.error;
}
// Exhaustiveness checking
type Action =
| { type: 'create'; payload: string }
| { type: 'delete'; id: number };
function handle(action: Action) {
switch (action.type) {
case 'create': return action.payload;
case 'delete': return action.id;
default: {
const _exhaustive: never = action;
throw new Error(`Unhandled: ${_exhaustive}`);
}
}
}
TypeScript types disappear at runtime. Use validation libraries for external data (APIs, forms, config files).
| Library | Bundle Size | Speed | Best For |
|---|---|---|---|
| Zod | ~13.5kB | Baseline | Full-stack apps, tRPC integration |
| TypeBox | ~8kB | ~10x faster | OpenAPI, performance-critical |
| Valibot | ~1.4kB | ~2x faster | Edge functions, minimal bundles |
import { z } from "zod";
const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
role: z.enum(["admin", "user", "guest"]),
});
type User = z.infer<typeof UserSchema>;
// Validate external data
function parseUser(input: unknown): User {
return UserSchema.parse(input);
}
→ See runtime-validation.md for complete Zod, TypeBox, and Valibot patterns
Need to choose between type vs interface?
interfacetypeinterface (default)Need generics or union types?
Dealing with unknown data?
unknown (type-safe)any (temporarily)Need runtime validation?
→ See decision-trees.md for comprehensive decision frameworks
Property does not exist on type → Define proper interface or use optional properties
Type is not assignable → Fix property types or use runtime validation (Zod)
Object is possibly 'undefined' → Use optional chaining (?.) or type guards
Cannot find module → Check file extensions (.js for ESM) and module resolution
Slow compilation → Enable incremental, use skipLibCheck, consider esbuild/swc
→ See troubleshooting.md for detailed solutions with examples
📐 Advanced Types - Conditional types, mapped types, infer keyword, recursive types. Load when building complex type utilities or generic libraries.
⚙️ Configuration - Complete tsconfig.json guide, project references, monorepo patterns. Load when setting up new projects or optimizing builds.
🔒 Runtime Validation - Zod, TypeBox, Valibot deep patterns, error handling, integration strategies. Load when implementing API validation or form handling.
✨ Advanced Patterns 2025 - TypeScript 5.2+ features: using keyword, stable decorators, import type behavior, satisfies with generics. Load when using modern language features.
🌳 Decision Trees - Clear decision frameworks for type vs interface, generics vs unions, unknown vs any, validation library selection, type narrowing strategies, and module resolution. Load when making TypeScript design decisions.
🔧 Troubleshooting - Common TypeScript errors and fixes, type inference issues, module resolution problems, tsconfig misconfigurations, build performance optimization, and type compatibility errors. Load when debugging TypeScript issues.
Stop and reconsider if:
any instead of unknown for external dataas without runtime validation@ts-ignore without clear justificationnoUncheckedIndexedAccessWhen using Core, these skills enhance your workflow:
[Full documentation available in these skills if deployed in your bundle]