TypeScript Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• configs/typescript/tsconfig.base.json
• configs/typescript/tsconfig.react.json
• configs/eslint/typescript.js
• skills/initialize/initialize-eng-platform.md
• README.md
• package.json

TypeScript Configuration within the Engineering Platform establishes a unified set of type-safety standards, compiler options, and linting rules shared across all organization projects. By providing centralized base configurations, the platform ensures that both frontend and backend projects maintain consistent compilation behaviors and strict type enforcement, facilitating easier maintenance and reducing runtime errors.

This system is designed around a "base-and-extend" architecture, where specific project types (such as React applications) inherit from a foundational configuration. This structure allows projects to adopt organizational standards while maintaining the flexibility to add project-specific overrides when necessary.

Configuration Architecture

The platform's TypeScript infrastructure is divided into two primary layers: compiler configuration and static analysis (linting). The compiler configuration uses JSON-based inheritance, while static analysis utilizes ESLint with TypeScript-specific plugins to enforce architectural and coding standards.

The diagram above shows the inheritance hierarchy and the relationship between compiler settings and linting configurations.
Sources: configs/typescript/tsconfig.base.json, configs/typescript/tsconfig.react.json, configs/eslint/typescript.js

Foundational Compiler Options

The tsconfig.base.json file serves as the core of the TypeScript system. It defines strict type-checking rules and modern ECMAScript target settings that apply to all projects utilizing the platform.

Category	Key Options	Purpose
Type Checking	strict, noImplicitAny, strictNullChecks	Enforces the highest level of type safety.
Modules	moduleResolution: "node", esModuleInterop	Ensures compatibility with Node.js and CommonJS modules.
Compilation	target: "ES2020", lib: ["ES2020"]	Sets modern JavaScript as the compilation output target.
Path Mapping	baseUrl: "."	Provides a base for relative module resolution.

Sources: configs/typescript/tsconfig.base.json, README.md:100-105

Specialized Configurations

For specialized environments like React, the platform provides specific extensions. These configurations override or add to the base settings to support JSX and specific library requirements.

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["DOM", "DOM.Iterable", "ESNext"]
  }
}

Sources: configs/typescript/tsconfig.react.json

Static Analysis and Linting

The platform enforces TypeScript standards through a specialized ESLint configuration found in configs/eslint/typescript.js. This configuration integrates the @typescript-eslint/parser and @typescript-eslint/eslint-plugin to provide deep analysis of the abstract syntax tree (AST) with type information.

Core Linting Rules

The configuration enables "Recommended" and "Recommended Requiring Type Checking" rule sets. It specifically enforces rules that prevent common asynchronous pitfalls and maintain naming consistency.

• Asynchronous Safety: Rules like @typescript-eslint/no-floating-promises and @typescript-eslint/no-misused-promises are set to error to prevent unhandled rejections.
• Strict Boolean Expressions: Enforces explicit boolean checks for strings, numbers, and nullable objects.
• Naming Conventions: Enforces PascalCase for interfaces, types, and enums, while variables use camelCase or UPPER_CASE.

Sources: configs/eslint/typescript.js:33-85

Type Safety Enforcement

The linting layer bridges the gap between the compiler and developer intent by prohibiting certain patterns that the compiler might otherwise allow.

Rule ID	Severity	Description
no-explicit-any	Error	Prohibits the use of the any type to maintain type integrity.
await-thenable	Error	Ensures await is only used on promises or thenables.
prefer-nullish-coalescing	Warn	Suggests ?? over `
no-unused-vars	Error	Prevents code bloat by detecting unused variables (ignores underscores).

Sources: configs/eslint/typescript.js:34-58

Project Integration and Skills

The platform provides automated routines for initializing these configurations in new or existing repositories. The initialize skill automates the setup of these files to ensure projects start with the correct standards.

This flow illustrates how the initialize skill sets up the TypeScript environment.
Sources: skills/initialize/initialize-eng-platform.md:55-85

Implementation Protocols

When setting up a project, the following file structure and dependencies are required as defined in the platform's root package.json and initialization scripts:

1. Dependencies: typescript, @typescript-eslint/parser, and @typescript-eslint/eslint-plugin.
2. Configuration Entry Point: A local tsconfig.json that extends the platform's base or React-specific config.
3. Linting Integration: An .eslintrc.js file that references the platform's TypeScript rules.

Sources: package.json:42-45, skills/initialize/initialize-eng-platform.md:55-65

Conclusion

The TypeScript Configuration in the Engineering Platform is a robust framework for maintaining code quality. By combining strict compiler options in tsconfig.base.json with aggressive linting in configs/eslint/typescript.js, the platform ensures that developers across various projects adhere to the same high standards of type safety and maintainability. This unified approach facilitates the extraction of domain-agnostic tools and scripts, as the underlying code structure remains predictable and standardized.