Google TypeScript Best Practices

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 to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new TypeScript code

• Organizing modules and imports

• Designing type annotations and interfaces

• Creating classes and functions

• Reviewing code for style consistency

• Refactoring existing TypeScript code

Rule Categories by Priority

Priority Category Impact Prefix

1 Module Organization CRITICAL module-

2 Type Safety CRITICAL types-

3 Class Design HIGH class-

4 Function Patterns HIGH func-

5 Control Flow MEDIUM-HIGH control-

6 Error Handling MEDIUM error-

7 Naming & Style MEDIUM naming-

8 Literals & Coercion LOW-MEDIUM literal-

Quick Reference

1. Module Organization (CRITICAL)

• module-named-exports

• Use named exports over default exports

• module-no-mutable-exports

• Avoid mutable exports

• module-es6-modules

• Use ES6 modules exclusively

• module-no-namespaces

• Avoid TypeScript namespaces

• module-import-paths

• Use relative paths for project imports

• module-import-type

• Use import type for type-only imports

• module-export-api-surface

• Minimize exported API surface

2. Type Safety (CRITICAL)

• types-no-any

• Never use the any type

• types-prefer-interfaces

• Prefer interfaces over type aliases for objects

• types-explicit-structural

• Explicitly annotate structural types

• types-nullable-patterns

• Handle nullable types correctly

• types-array-syntax

• Use consistent array type syntax

• types-no-wrapper-types

• Never use wrapper object types

• types-prefer-map-set

• Prefer Map and Set over index signatures

• types-no-empty-object

• Avoid empty object type

3. Class Design (HIGH)

• class-parameter-properties

• Use parameter properties for constructor assignment

• class-readonly-properties

• Mark properties readonly when never reassigned

• class-no-private-fields

• Use TypeScript private over private fields

• class-no-static-containers

• Avoid container classes with only static members

• class-constructor-parens

• Always use parentheses in constructor calls

• class-no-prototype-manipulation

• Never manipulate prototypes directly

4. Function Patterns (HIGH)

• func-declarations-over-expressions

• Prefer function declarations over expressions

• func-arrow-concise-bodies

• Use concise arrow function bodies appropriately

• func-avoid-this-rebinding

• Avoid rebinding this

• func-rest-parameters

• Use rest parameters over arguments

• func-generator-syntax

• Use correct generator function syntax

• func-default-parameters

• Use default parameters sparingly

5. Control Flow (MEDIUM-HIGH)

• control-always-use-braces

• Always use braces for control structures

• control-triple-equals

• Always use triple equals

• control-for-of-iteration

• Prefer for-of over for-in for arrays

• control-switch-default

• Always include default case in switch

• control-no-assignment-in-condition

• Avoid assignment in conditional expressions

6. Error Handling (MEDIUM)

• error-throw-errors

• Always throw Error instances

• error-catch-unknown

• Type catch clause variables as unknown

• error-empty-catch-comments

• Document empty catch blocks

• error-avoid-assertions

• Avoid type and non-null assertions

7. Naming & Style (MEDIUM)

• naming-identifier-styles

• Use correct identifier naming styles

• naming-descriptive-names

• Use descriptive names

• naming-no-decorative-underscores

• Avoid decorative underscores

• naming-no-interface-prefix

• No I prefix for interfaces

• naming-constants

• Use CONSTANT_CASE for true constants

8. Literals & Coercion (LOW-MEDIUM)

• literal-single-quotes

• Use single quotes for strings

• literal-number-formats

• Use correct number literal formats

• literal-explicit-coercion

• Use explicit type coercion

• literal-array-constructor

• Avoid Array constructor

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

AGENTS.md Complete compiled guide with all rules

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information