TypeScript

Version 0.1.0
Google
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive TypeScript style guide based on Google's internal standards, designed for AI agents and LLMs. Contains 45 rules across 8 categories, prioritized by impact from critical (module organization, type safety) to incremental (literals and coercion). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Module Organization — CRITICAL
   • 1.1 Avoid Mutable Exports — CRITICAL (prevents hard-to-track state mutations)
   • 1.2 Avoid TypeScript Namespaces — CRITICAL (prevents runtime overhead and enables tree-shaking)
   • 1.3 Minimize Exported API Surface — HIGH (reduces coupling and maintenance burden)
   • 1.4 Use ES6 Modules Exclusively — CRITICAL (enables tree-shaking and static analysis)
   • 1.5 Use Import Type for Type-Only Imports — HIGH (reduces bundle size by eliminating runtime imports)
   • 1.6 Use Named Exports Over Default Exports — CRITICAL (catches import typos at compile time)
   • 1.7 Use Relative Paths for Project Imports — HIGH (improves refactoring flexibility and reduces coupling)
2. Type Safety — CRITICAL
   • 2.1 Avoid Empty Object Type — HIGH (prevents unexpected type widening)
   • 2.2 Explicitly Annotate Structural Types — CRITICAL (catches type mismatches at declaration site)
   • 2.3 Handle Nullable Types Correctly — CRITICAL (prevents null reference errors)
   • 2.4 Never Use the any Type — CRITICAL (prevents undetected type errors throughout codebase)
   • 2.5 Never Use Wrapper Object Types — CRITICAL (prevents type confusion and boxing overhead)
   • 2.6 Prefer Interfaces Over Type Aliases for Objects — CRITICAL (better error messages and IDE performance)
   • 2.7 Prefer Map and Set Over Index Signatures — HIGH (O(1) operations with proper typing)
   • 2.8 Use Consistent Array Type Syntax — HIGH (improves readability and consistency)
3. Class Design — HIGH
   • 3.1 Always Use Parentheses in Constructor Calls — MEDIUM (consistent syntax and prevents parsing ambiguity)
   • 3.2 Avoid Container Classes with Only Static Members — HIGH (reduces unnecessary abstraction and enables tree-shaking)
   • 3.3 Mark Properties Readonly When Never Reassigned — HIGH (prevents accidental mutations and enables optimizations)
   • 3.4 Never Manipulate Prototypes Directly — HIGH (prevents VM deoptimization and unpredictable behavior)
   • 3.5 Use Parameter Properties for Constructor Assignment — HIGH (reduces boilerplate by 50%)
   • 3.6 Use TypeScript Private Over Private Fields — HIGH (consistent access control without runtime overhead)
4. Function Patterns — HIGH
   • 4.1 Avoid Rebinding this — HIGH (prevents subtle bugs from this binding issues)
   • 4.2 Prefer Function Declarations Over Expressions — HIGH (hoisting enables cleaner code organization)
   • 4.3 Use Concise Arrow Function Bodies Appropriately — MEDIUM (improves readability for simple transforms)
   • 4.4 Use Correct Generator Function Syntax — MEDIUM (consistent, readable generator definitions)
   • 4.5 Use Default Parameters Sparingly — MEDIUM (prevents side effects in parameter defaults)
   • 4.6 Use Rest Parameters Over arguments — HIGH (type-safe variadic functions)
5. Control Flow — MEDIUM-HIGH
   • 5.1 Always Include Default Case in Switch — MEDIUM (prevents silent failures on unexpected values)
   • 5.2 Always Use Braces for Control Structures — MEDIUM-HIGH (prevents bugs from misleading indentation)
   • 5.3 Always Use Triple Equals — MEDIUM-HIGH (prevents type coercion bugs)
   • 5.4 Avoid Assignment in Conditional Expressions — MEDIUM (prevents accidental assignment bugs)
   • 5.5 Prefer for-of Over for-in for Arrays — MEDIUM-HIGH (prevents prototype property enumeration bugs)
6. Error Handling — MEDIUM
   • 6.1 Always Throw Error Instances — MEDIUM (provides stack traces for debugging)
   • 6.2 Avoid Type and Non-Null Assertions — MEDIUM (prevents hiding type errors)
   • 6.3 Document Empty Catch Blocks — MEDIUM (explains intentional error suppression)
   • 6.4 Type Catch Clause Variables as Unknown — MEDIUM (enforces safe error handling)
7. Naming & Style — MEDIUM
   • 7.1 Avoid Decorative Underscores — MEDIUM (cleaner code without misleading conventions)
   • 7.2 No I Prefix for Interfaces — MEDIUM (cleaner type names without Hungarian notation)
   • 7.3 Use CONSTANT_CASE for True Constants — MEDIUM (distinguishes immutable values from variables)
   • 7.4 Use Correct Identifier Naming Styles — MEDIUM (improves code readability and consistency)
   • 7.5 Use Descriptive Names — MEDIUM (improves code maintainability)
8. Literals & Coercion — LOW-MEDIUM
   • 8.1 Avoid Array Constructor — LOW-MEDIUM (prevents confusing Array constructor behavior)
   • 8.2 Use Correct Number Literal Formats — LOW-MEDIUM (consistent and readable numeric literals)
   • 8.3 Use Explicit Type Coercion — LOW-MEDIUM (prevents unexpected coercion behavior)
   • 8.4 Use Single Quotes for Strings — LOW-MEDIUM (consistent string syntax throughout codebase)

References

1. https://google.github.io/styleguide/tsguide.html
2. https://www.typescriptlang.org/docs/handbook/
3. https://google.github.io/styleguide/jsguide.html

Source Files

This document was compiled from individual reference files. For detailed editing or extension: