TypeScript Core

Comprehensive guidance for TypeScript development with strict type safety, functional patterns, and modern tooling.

Core Principles

Follow these fundamental principles in all TypeScript work:

1. TypeScript Only (Strict Mode) - Always enable strict mode and all type-checking flags
2. Simplicity First (KISS + YAGNI) - Do the simplest thing that works, avoid speculative architecture
3. Type Safety - Use Result/Effect types instead of throwing exceptions
4. Functional Patterns - Prefer composition, immutability, and pure functions
5. User Experience First - Clear error messages, predictable behavior

See principles.md for detailed guidance.

Quick Start

Setting Up a New TypeScript Project

1. Choose the appropriate tsconfig template based on project type:

   • Node.js backend → assets/tsconfig-templates/strict-node.json
   • React frontend → assets/tsconfig-templates/strict-react.json
   • Library/Package → assets/tsconfig-templates/library.json
   • Monorepo → assets/tsconfig-templates/monorepo-base.json

2. Install required dependencies - Always use the latest versions with pnpm:

   pnpm add -D typescript @types/node
   pnpm add effect zod true-myth @logtape/logtape
   

3. Configure strict linting - See strict-configuration.md for ESLint and Prettier setup

4. Organize project structure - Follow feature-oriented layout from project-structure.md

Resolving TypeScript Errors

When encountering TypeScript compilation errors:

1. Read the full error message - Includes file, line, and often helpful suggestions
2. Check common-errors.md - Quick solutions for frequent errors
3. Verify strict mode configuration - Ensure all flags from strict-configuration.md are enabled
4. Use type utilities - See type-utilities.md for built-in helpers

TypeScript Configuration

All projects must use strict TypeScript configuration to catch errors early and maintain code quality.

Key requirements:

• Enable strict: true (includes all strict type-checking options)
• Enable noUncheckedIndexedAccess: true (not in strict by default, prevents undefined array access issues)
• Use latest TypeScript version
• Zero compiler errors or warnings before commit

See strict-configuration.md for complete tsconfig.json and ESLint setup.

Type Safety & Patterns

Handling Nullable Values

Prefer True Myth's Maybe type over null/undefined:

import Maybe from 'true-myth/maybe';

// Instead of: User | null
function findUser(id: string): Maybe<User> {
  const user = db.findById(id);
  return Maybe.of(user);
}

// Use with chaining
const userName = findUser("123")
  .map(user => user.name)
  .unwrapOr("Unknown");

Handling Errors

Use Result types instead of throwing exceptions:

import Result from 'true-myth/result';

// Instead of throwing
function parseConfig(data: string): Result<Config, ParseError> {
  try {
    const parsed = JSON.parse(data);
    return Result.ok(parsed);
  } catch (e) {
    return Result.err(new ParseError("Invalid JSON", e));
  }
}

// Use with pattern matching
parseConfig(data)
  .match({
    Ok: config => console.log("Config loaded:", config),
    Err: error => console.error("Parse failed:", error)
  });

For complex async operations, prefer Effect over raw Promises - See error-handling.md for complete strategy.

TypeScript Utility Types

Leverage built-in utility types for type transformations:

• Partial<T> - Make all properties optional (partial updates)
• Required<T> - Make all properties required
• Pick<T, K> - Extract specific properties (DTOs, API responses)
• Omit<T, K> - Exclude properties (hide sensitive fields)
• Record<K, V> - Type-safe dictionaries/maps
• ReturnType<T> - Extract function return type
• Parameters<T> - Extract function parameter types

See type-utilities.md for comprehensive guide with examples.

Coding Patterns

Composition Over Inheritance

Favor composing functionality rather than class hierarchies:

// Prefer this
const withLogging = <T extends (...args: any[]) => any>(fn: T) => {
  return ((...args: Parameters<T>) => {
    logger.info("Calling function", { args });
    return fn(...args);
  }) as T;
};

// Over this
class LoggableService extends BaseService {
  // ...
}

Railway-Oriented Error Flow

Chain operations with Effect or Result types to handle errors gracefully:

import { pipe } from 'effect';
import Result from 'true-myth/result';

const result = pipe(
  validateInput(data),
  Result.andThen(processData),
  Result.andThen(saveToDatabase),
  Result.mapErr(err => new ApplicationError("Process failed", err))
);

See patterns.md for complete pattern library including immutability, pattern matching, and concurrency patterns.

Project Organization

Structure projects by feature, not by technical type:

src/
├── features/
│   └── users/
│       ├── components/
│       ├── services/
│       ├── hooks/
│       └── types.ts
├── lib/
│   ├── api/
│   └── utils/
└── state/

See project-structure.md for complete layouts for web apps, backends, CLIs, and monorepos.

Package Ecosystem

Always Use (Standard Toolkit)

These packages are included by default in new projects:

• Effect - Functional effect system for async/concurrent operations
• Zod - Schema validation at boundaries (API inputs, env vars)
• True Myth - Maybe/Result types for null safety and error handling
• LogTape - Structured logging with redaction and integrations
• Oclif - CLI framework (for CLI projects)

See packages-always-use.md for detailed rationale and usage.

Utility Libraries

Context-specific packages for common needs:

• Date handling, string manipulation, async utilities, etc.
• See packages-utilities.md

CLI Tools

For command-line applications:

• Ink (rich TUI), Inquirer (prompts), Ora (spinners), cli-progress
• See packages-cli.md

Testing

Use Vitest with Testing Library for all tests:

import { describe, it, expect } from 'vitest';

describe('UserService', () => {
  it('should create user with valid input', () => {
    const result = createUser({ name: "Alice", email: "alice@example.com" });
    expect(result.isOk()).toBe(true);
  });
});

See testing.md for complete testing strategy including React component testing, Effect testing, and MSW for API mocking.

Code Review Standards

Before submitting code:

1. Zero errors - tsc --noEmit passes with no errors
2. Zero warnings - ESLint and Prettier checks pass
3. Tests pass - All tests green
4. Follows patterns - Uses Result/Maybe, Effect for async, proper error handling
5. Proper naming - See naming.md for conventions

See code-review.md for complete checklist.

Dependency Management

• Always use latest versions - Update dependencies regularly
• Use pnpm - Required package manager for all projects
• Audit security - Run pnpm audit before releases
• Lock file committed - pnpm-lock.yaml always in version control

See dependencies.md for update strategies and security practices.

Reference Files

Configuration & Setup:

• strict-configuration.md - Complete TypeScript and ESLint configuration
• project-structure.md - Directory layouts for different project types
• dependencies.md - Dependency management and updates

Patterns & Practices:

• principles.md - Core development principles (KISS, YAGNI, UX-first)
• patterns.md - Code patterns (composition, immutability, railway-oriented)
• error-handling.md - Complete error handling strategy
• naming.md - Naming conventions for files, functions, and variables
• testing.md - Testing approaches and best practices
• code-review.md - Code review standards and checklist

TypeScript-Specific:

• common-errors.md - Quick solutions for TypeScript compilation errors
• type-utilities.md - Built-in utility types reference

Packages:

• packages-always-use.md - Standard toolkit (Effect, Zod, LogTape, etc.)
• packages-utilities.md - Utility libraries for specific needs
• packages-cli.md - CLI-specific tooling

Templates

Pre-configured tsconfig.json files for quick project setup:

• strict-node.json - Node.js backend with strict mode
• strict-react.json - React application with strict mode
• library.json - Library/package configuration
• monorepo-base.json - Monorepo base configuration