--- name: typescript slug: typescript license: MIT description: > Provide best-practice coding conventions and generate standards-compliant TypeScript code. ---

TypeScript Style Guide Skill

> Activation: This skill activates whenever the user says or implies TypeScript. It responds > with standards-compliant TypeScript code and can explain any rule on demand.

---

Table of Contents

1. General Principles
2. Naming Conventions
3. Types & Interfaces
4. Enums
5. Variables & Constants
6. Functions
7. Classes
8. Modules & Imports
9. Generics
10. Error Handling
11. Async / Await & Promises
12. Comments & Documentation
13. Formatting & Style
14. Null & Undefined Handling
15. Type Assertions & Guards
16. React & JSX (when applicable)
17. Testing Conventions
18. Tooling & Configuration

---

1. General Principles

• Strict mode always: Enable "strict": true in tsconfig.json. This turns on noImplicitAny,

strictNullChecks, strictFunctionTypes, and more.

• Prefer readability over cleverness: Code is read far more often than written. Favour explicit,

self-documenting code.

• Minimise any: Treat every use of any as tech debt. Prefer unknown when the type is

truly not known, or use generics.

• Immutability by default: Use const over let; prefer readonly properties and

ReadonlyArray / Readonly utility types.

• Single responsibility: Each file, class, and function should have one clear purpose.
• Keep files small: A file should ideally stay under 400 lines. If it grows larger, consider

splitting it.

---

2. Naming Conventions

| Construct | Convention | Example | | ----------------------- | ----------------------- | -------------------------------- | | Variable / Function | camelCase | getUserName, isActive | | Boolean variable | camelCase with prefix | isLoading, hasAccess, canEdit | | Constant (module) | UPPER_SNAKE_CASE | MAX_RETRY_COUNT, API_BASE_URL| | Constant (local) | camelCase | const defaultTimeout = 3000 | | Class | PascalCase | UserService, HttpClient | | Interface | PascalCase | UserProfile, ApiResponse | | Type alias | PascalCase | UserId, Theme | | Enum | PascalCase | Direction, HttpStatus | | Enum member | PascalCase | Direction.Up, HttpStatus.Ok | | Generic parameter | Single uppercase letter or descriptive PascalCase | T, TKey, TValue | | File name | kebab-case.ts | user-service.ts, api-client.ts| | Test file name | kebab-case.test.ts or kebab-case.spec.ts | user-service.test.ts | | React component file| PascalCase.tsx | UserProfile.tsx | | Private field | camelCase (no _ prefix) | private count: number |

Additional Naming Rules

• Do NOT prefix interfaces with I (e.g., ~~IUser~~ → User).
• Do NOT suffix types/interfaces with Type or Interface.
• Use descriptive names. Avoid single-letter variables except for conventional usages like loop

indices (i, j) or generic type parameters (T, K, V).

• Acronyms of 2 characters stay uppercase (IO, ID); 3+ characters use PascalCase

(Http, Xml, Api).

---

3. Types & Interfaces

Prefer interface for Object Shapes

// ✅ Good — use interface for object shapes
interface User {
  readonly id: string;
  name: string;
  email: string;
}

// ✅ Good — use type for unions, intersections, mapped types
type Status = 'active' | 'inactive' | 'suspended';
type Result<T> = Success<T> | Failure;

When to Use type vs interface

| Use interface when … | Use type when … | | ---------------------------------------------- | ------------------------------------------ | | Defining the shape of an object or class | Creating union or intersection types | | You want declaration merging | Using mapped / conditional types | | Extending other interfaces | Aliasing primitive or tuple types |

Rules

• Always annotate function return types explicitly for public APIs.
• Let TypeScript infer types for local variables when the type is obvious.
• Prefer type over interface for function signatures:

```typescript type Comparator = (a: T, b: T) => number; ```

• Avoid empty interfaces. If extending, include at least a comment explaining intent.
• Use Record instead of { [key: string]: V }.
• Use utility types (Partial, Pick, Omit, Required) to derive types

rather than duplicating.

---

4. Enums

Prefer String Enums

// ✅ Good — string enum for readability and debuggability
enum Direction {
  Up = 'UP',
  Down = 'DOWN',
  Left = 'LEFT',
  Right = 'RIGHT',
}

When to Use const Enum or Union Types

// ✅ Good — const enum for zero-runtime-cost enums (no reverse mapping needed)
const enum HttpMethod {
  Get = 'GET',
  Post = 'POST',
  Put = 'PUT',
  Delete = 'DELETE',
}

// ✅ Also good — string literal union (simpler, tree-shakeable)
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';

Rules

• Do NOT use numeric enums without explicit values (auto-increment is fragile).
• Prefer string literal union types over enums when the set is small and no namespace features

are needed.

• Never mix string and numeric members in the same enum.

---

5. Variables & Constants

// ✅ Good
const maxRetries = 3;
const baseUrl = 'https://api.example.com';
let currentAttempt = 0;

// ❌ Bad — using var
var legacyValue = 'old';

// ❌ Bad — using let when value never changes
let neverReassigned = 42;

Rules

• Always use const unless the variable needs reassignment; then use let.
• Never use var.
• Declare variables as close to their first usage as possible.
• One variable declaration per statement.
• Prefer destructuring for extracting properties:

```typescript // ✅ Good const { name, age } = user;

// ❌ Bad const name = user.name; const age = user.age; ```

• Use as const for immutable literal objects / arrays:

```typescript const ROUTES = { home: '/', about: '/about', contact: '/contact', } as const; ```

---

6. Functions

Function Declarations

// ✅ Good — explicit return type for public functions
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// ✅ Good — arrow function for callbacks / short lambdas
const double = (n: number): number => n * 2;

// ✅ Good — use default parameters instead of optional + fallback
function createUser(name: string, role: Role = Role.Viewer): User {
  // ...
}

Rules

...