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<T> / Readonly<T> 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:

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

• Avoid empty interfaces. If extending, include at least a comment explaining intent.
• Use Record<K, V> instead of { [key: string]: V }.
• Use utility types (Partial<T>, Pick<T, K>, Omit<T, K>, Required<T>) 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:

  // ✅ Good
  const { name, age } = user;
  
  // ❌ Bad
  const name = user.name;
  const age = user.age;
  

• Use as const for immutable literal objects / arrays:

  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

• Annotate return types for all exported / public functions.
• Prefer arrow functions for callbacks and inline functions.
• Prefer function declarations for top-level named functions (they are hoisted and more readable in stack traces).
• Maximum parameters: 3. If more are needed, group them into an options object:

  // ✅ Good
  interface CreateUserOptions {
    name: string;
    email: string;
    role?: Role;
    department?: string;
  }
  function createUser(options: CreateUserOptions): User { ... }
  
  // ❌ Bad — too many positional parameters
  function createUser(name: string, email: string, role: Role, dept: string): User { ... }
  

• Do not use arguments; use rest parameters (...args) instead.
• Avoid Function type. Use specific function signatures.
• Keep functions small — ideally under 30 lines of logic.
• Functions should do one thing.
• Prefer early returns to reduce nesting:

  // ✅ Good
  function getDiscount(user: User): number {
    if (!user.isPremium) return 0;
    if (user.yearsActive < 2) return 5;
    return 10;
  }
  

---

7. Classes

// ✅ Good
class UserService {
  private readonly repository: UserRepository;

  constructor(repository: UserRepository) {
    this.repository = repository;
  }

  async findById(id: string): Promise<User | undefined> {
    return this.repository.get(id);
  }
}

Rules

• Prefer composition over inheritance.
• Use readonly for properties that should not change after construction.
• Member ordering:
  1. Static fields
  2. Instance fields
  3. Constructor
  4. Static methods
  5. Public methods
  6. Protected methods
  7. Private methods
• Use explicit access modifiers (public, protected, private) on every member.
• Do NOT prefix private members with _. TypeScript's private keyword is sufficient.
• Use # (ES private fields) when true runtime privacy is required.
• Prefer parameter properties for simple constructor-only assignments:

  class Logger {
    constructor(private readonly prefix: string) {}
  }
  

• Avoid classes with only static methods — use plain functions in a module instead.
• Implement interfaces explicitly:

  class UserRepositoryImpl implements UserRepository { ... }
  

---

8. Modules & Imports

// ✅ Good — named exports
export function parseConfig(raw: string): Config { ... }
export interface Config { ... }

// ✅ Good — re-export barrel file (index.ts)
export { parseConfig } from './parse-config';
export type { Config } from './parse-config';

Rules

• Prefer named exports over default exports (better refactoring, auto-import support).
• Use default exports only for React components if the project convention requires it.
• Use import type / export type for type-only imports to help bundlers tree-shake:

  import type { User } from './user';
  

• Group and order imports:
  1. Node built-ins (node:fs, node:path)
  2. External packages (react, lodash)
  3. Internal aliases (@/utils, @/components)
  4. Relative parent (../)
  5. Relative sibling (./)
• Separate each group with a blank line.
• Do NOT use wildcard imports (import * as) unless re-exporting a module namespace.
• Keep barrel files (index.ts) thin — do not add logic.

---

9. Generics

// ✅ Good — descriptive when intent is ambiguous
function merge<TTarget, TSource>(target: TTarget, source: TSource): TTarget & TSource {
  return { ...target, ...source };
}

// ✅ Good — single-letter when intent is obvious
function identity<T>(value: T): T {
  return value;
}

// ✅ Good — constrained generics
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

Rules

• Use a single uppercase letter (T, U, K, V) for simple generics.
• Use descriptive PascalCase prefixed with T (TKey, TValue, TResult) when there are multiple type parameters or the purpose is not obvious.
• Always add constraints when possible (<T extends SomeType>).
• Avoid unnecessary generics — if a type parameter is used only once, it's likely not needed.
• Prefer generic utility types (Array<T>, Promise<T>, Map<K, V>) over their shorthand where readability benefits.

---

10. Error Handling

// ✅ Good — custom error class
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
  ) {
    super(message);
    this.name = 'AppError';
  }
}

// ✅ Good — typed error handling
function parseJson<T>(raw: string): T {
  try {
    return JSON.parse(raw) as T;
  } catch (error) {
    throw new AppError(
      `Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`,
      'PARSE_ERROR',
      400,
    );
  }
}

Rules

• Never swallow errors silently (empty catch blocks).
• Use custom error classes that extend Error for domain-specific errors.
• Type the catch variable as unknown (default in TS 4.4+) and narrow before use.
• Prefer Result / Either patterns for expected failures in libraries:

  type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
  

• Always clean up resources in finally blocks or use disposable patterns.
• Log errors with sufficient context (operation name, input summary, stack trace).

---

11. Async / Await & Promises

// ✅ Good — async/await
async function fetchUser(id: string): Promise<User> {
  const response = await httpClient.get<User>(`/users/${id}`);
  return response.data;
}

// ✅ Good — parallel execution
async function fetchDashboard(userId: string): Promise<Dashboard> {
  const [user, posts, notifications] = await Promise.all([
    fetchUser(userId),
    fetchPosts(userId),
    fetchNotifications(userId),
  ]);
  return { user, posts, notifications };
}

Rules

• Prefer async/await over .then() chains for readability.
• Always annotate return types as Promise<T>.
• Use Promise.all() for independent concurrent operations.
• Use Promise.allSettled() when failures should not abort sibling operations.
• Never use new Promise() when an async function suffices (avoid the explicit-construction antipattern).
• Avoid async void functions — they cannot be await-ed and swallow errors. Exception: event handlers where the framework requires void.
• Prefer for...of with await for sequential async iteration, not forEach.

---

12. Comments & Documentation

/**
 * Calculate the compound interest for a principal amount.
 *
 * @param principal - The initial amount of money.
 * @param rate - The annual interest rate (decimal, e.g. 0.05 for 5%).
 * @param times - Number of times interest is compounded per year.
 * @param years - Number of years the money is invested.
 * @returns The total amount after compound interest.
 *
 * @example
 * ```typescript
 * const total = compoundInterest(1000, 0.05, 12, 10);
 * // total ≈ 1647.01
 * ```
 */
function compoundInterest(
  principal: number,
  rate: number,
  times: number,
  years: number,
): number {
  return principal * Math.pow(1 + rate / times, times * years);
}

Rules

• Use TSDoc (/** */) for all public APIs, exported functions, classes, interfaces, and types.
• Include @param, @returns, @throws, and @example tags where applicable.
• Do NOT comment obvious code. The code should be self-documenting.
• Use // TODO: with a ticket number for planned improvements.
• Use // FIXME: for known issues that need resolution.
• Use // HACK: for workarounds that should be revisited.
• Never leave commented-out code in the main branch.
• Place file-level comments at the top if the module's purpose is not obvious from its name.
• Keep comments up-to-date with code changes.

---

13. Formatting & Style

General

• Indentation: 2 spaces (no tabs).
• Semicolons: Required at the end of every statement.
• Quotes: Single quotes (') for strings; backticks (`) for template literals.
• Trailing commas: Always use in multi-line constructs (arrays, objects, parameters, generics).
• Max line length: 100 characters (soft limit), 120 characters (hard limit).
• Braces: Required for all control structures, even single-line bodies.
• Blank lines: One blank line between top-level declarations; no multiple consecutive blank lines.

Specific Patterns

// ✅ Good — braces always, even for single-line if
if (isValid) {
  process();
}

// ❌ Bad
if (isValid) process();

// ✅ Good — trailing comma
const config = {
  host: 'localhost',
  port: 3000,
  debug: true,
};

// ✅ Good — consistent object shorthand
const name = 'Alice';
const user = { name, age: 30 };

Tooling

• Use Prettier for auto-formatting with the following baseline config:

  {
    "semi": true,
    "singleQuote": true,
    "trailingComma": "all",
    "printWidth": 100,
    "tabWidth": 2,
    "arrowParens": "always"
  }
  

• Use ESLint with @typescript-eslint/eslint-plugin and @typescript-eslint/parser for linting.

---

14. Null & Undefined Handling

// ✅ Good — optional chaining
const city = user?.address?.city;

// ✅ Good — nullish coalescing
const displayName = user.nickname ?? user.name ?? 'Anonymous';

// ✅ Good — explicit null checks for critical paths
function getUser(id: string): User {
  const user = repository.findById(id);
  if (user === undefined) {
    throw new AppError(`User not found: ${id}`, 'USER_NOT_FOUND', 404);
  }
  return user;
}

Rules

• Enable strictNullChecks (included in strict mode).
• Prefer undefined over null as the "absence of value" indicator, unless interacting with external APIs that use null.
• Use optional chaining (?.) and nullish coalescing (??) instead of manual checks.
• Do NOT use non-null assertion (!) unless you can prove the value is always defined (add a comment explaining why).
• Prefer the satisfies operator (TS 5.0+) to validate types without widening.

---

15. Type Assertions & Guards

// ✅ Good — type guard function
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value
  );
}

// ✅ Good — discriminated union
interface Success<T> {
  kind: 'success';
  data: T;
}
interface Failure {
  kind: 'failure';
  error: Error;
}
type Result<T> = Success<T> | Failure;

function handleResult<T>(result: Result<T>): T {
  switch (result.kind) {
    case 'success':
      return result.data;
    case 'failure':
      throw result.error;
  }
}

Rules

• Prefer type guards (is keyword) over type assertions (as).
• Use as const for literal narrowing, not as SpecificType.
• Use discriminated unions with a kind / type field for state machines and result types.
• Avoid as unknown as T double assertions — they are almost always a design smell.
• When assertions are necessary, add a comment justifying them.
• Use satisfies for type validation without assertion:

  const palette = {
    red: [255, 0, 0],
    green: '#00ff00',
  } satisfies Record<string, string | number[]>;
  

---

16. React & JSX (when applicable)

// ✅ Good — functional component with explicit props type
interface UserCardProps {
  readonly user: User;
  readonly onSelect?: (userId: string) => void;
}

export function UserCard({ user, onSelect }: UserCardProps): React.ReactElement {
  const handleClick = useCallback(() => {
    onSelect?.(user.id);
  }, [onSelect, user.id]);

  return (
    <div className="user-card" onClick={handleClick} role="button" tabIndex={0}>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
}

Rules

• Use function declarations or named function expressions for components (not anonymous).
• Define props as an interface (e.g., UserCardProps), not inline.
• Mark all props as readonly.
• Do NOT use React.FC — it is discouraged since React 18.
• Use React.ReactElement or React.ReactNode as return type annotation.
• Colocate styles, tests, and types with the component when practical.
• Prefer controlled components over uncontrolled.
• Memoize expensive computations with useMemo, stable callbacks with useCallback.
• Extract custom hooks when logic is reused across components.
• Component file structure:
  1. Imports
  2. Types / Interfaces
  3. Constants
  4. Component function
  5. Helper functions (private to the module)

---

17. Testing Conventions

// ✅ Good — descriptive test structure
describe('UserService', () => {
  describe('findById', () => {
    it('should return the user when the id exists', async () => {
      const user = await service.findById('user-1');
      expect(user).toEqual(expect.objectContaining({ id: 'user-1' }));
    });

    it('should return undefined when the id does not exist', async () => {
      const user = await service.findById('non-existent');
      expect(user).toBeUndefined();
    });
  });
});

Rules

• Test files are colocated or in a __tests__ directory.
• Name test files *.test.ts or *.spec.ts.
• Follow the Arrange → Act → Assert pattern.
• One assertion concept per test (multiple expect calls are okay if they test one logical assertion).
• Use descriptive test names that read like a sentence.
• Mock external dependencies; do NOT mock the module under test.
• Prefer dependency injection to make code testable.
• Aim for high test coverage on business logic; don't chase 100% on boilerplate.
• Use jest.fn() or equivalent for spies/mocks; type them properly:

  const mockFetch = jest.fn<Promise<User>, [string]>();
  

---

18. Tooling & Configuration

Recommended tsconfig.json (Baseline)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

Recommended ESLint Rules

Rule	Setting
@typescript-eslint/no-explicit-any	error
@typescript-eslint/explicit-function-return-type	warn (for exported functions)
@typescript-eslint/no-unused-vars	error
@typescript-eslint/consistent-type-imports	error
@typescript-eslint/no-non-null-assertion	warn
@typescript-eslint/prefer-nullish-coalescing	error
@typescript-eslint/prefer-optional-chain	error
@typescript-eslint/strict-boolean-expressions	warn
@typescript-eslint/naming-convention	error (configured per construct)

---

Usage

Natural Language Activation

Simply mention TypeScript in your conversation — the skill activates automatically.

Example prompts:

Prompt	Skill Response
"Write a TypeScript function to merge two objects deeply"	Generates a fully typed, standards-compliant deepMerge<T, U>() function following all rules above.
"Review my TypeScript code for style issues"	Analyses the provided code against this guide and suggests improvements.
"Convert this JavaScript to TypeScript"	Converts code, adds strict types, interfaces, and follows all naming / formatting conventions.
"What's the TypeScript best practice for error handling?"	Explains the Result pattern, custom error classes, and typed catch blocks per §10.
"Create a TypeScript React component for a data table"	Generates a well-typed functional component following §16 React rules with proper props interface.
"Set up a new TypeScript project"	Provides tsconfig.json, ESLint config, Prettier config, and project structure following §18.

Inline Rule References

You can ask about any specific section:

• "Explain TypeScript naming conventions" → References §2
• "How should I handle null in TypeScript?" → References §14
• "Show me TypeScript generic best practices" → References §9