Skip to content
Skills Library
Programming · Review & audit

typescript

/typescript

Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance.

Repository
stacc ↗
Licence
MIT
Last repository change
21.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance.

Original author description

Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance.

How it works

  1. Quick Start
  2. Workflow (use this order)
  3. Review Checklist
  4. Local Resources
  5. Configuration
  6. Type Definitions
  7. Type Safety
  8. Runtime Validation
  9. Enums and Unions
  10. Generics
Original SKILL.md headings · 296 lines, 945 words
SKILL.md preview
---
name: typescript
description: Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance.
---

# TypeScript Best Practices

## Quick Start

Apply these rules by default when touching TypeScript/JavaScript:

1. Enable `strict: true` in `tsconfig.json` (most impactful change)
2. Define clear type contracts with interfaces/type aliases
3. Use `unknown` instead of `any`; narrow with type guards
4. Implement runtime validation for external data (APIs, user input)
5. Prefer string literal unions over numeric enums
6. Use named exports, avoid default exports

## Workflow (use this order)

1. Clarify scope: new code, refactor, or review.
2. Enforce strictness in `tsconfig.json` (or confirm it is already strict).
3. Define explicit type contracts for inputs/outputs (interfaces/type aliases).
4. Replace `any` with `unknown` + narrowing/guards.
5. Add runtime validation for external data boundaries.
6. Normalize exports/imports and tighten API surfaces.
7. Add or update tests for changed behavior.

## Review Checklist

- Strict mode enabled and no `any` leaks.
- Public types are explicit and documented.
- Runtime validation exists for untrusted inputs.
- Literal unions used instead of numeric enums.
- Named exports only; imports are organized.
- Tests cover edge cases and error paths.

## Local Resources

Use the always-applied rule file in this folder:
- `typescript.mdc` (authoritative TypeScript/JSX guidance; read when you need the full rule text)

## Configuration

**Essential `tsconfig.json` settings:**

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "allowJs": true,
    "checkJs": true
  }
}
```

## Type Definitions

### Interfaces for Object Shapes

Use interfaces for object shapes and class contracts. Define in `.d.ts` or `.ts` files, reference via JSDoc in `.js` files.

```typescript
interface UserProfile {
  id: string;
  name: string;
  email: string;
  age?: number;
}
```

### Type Aliases for Unions & Complex Types

Use type aliases for unions, intersections, and tuples.

```typescript
type ID = string | number;
type UserRole = "admin" | "user" | "guest";
type Coords = [number, number];
```

## Type Safety

### Avoid `any`, Use `unknown`

`any` bypasses all type checks. `unknown` forces narrowing before use.

❌ **Bad:**
```typescript
function processData(data: any) {
  console.log(data.foo.bar); // No type safety
}
```

✅ **Good:**
```typescript
function processData(data: unknown) {
  if (typeof data === 'object' && data !== null && 'foo' in data) {
    const typed = data as { foo: { bar: string } };
    console.log(typed.foo.bar);
  }
}
```

## Runtime Validation

TypeScript's checks are compile-time only. For external data (APIs, user input), implement runtime validation with type guards.

### Type Guards for Primitives

```typescript
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isNumber(value: unknown): value is number {
  return typeof value === 'number' && !isNaN(value);
}
```

### Type Guards for Complex Objects

```typescript
interface Product {
  id: string;
  name: string;
  price: number;
}

function isProduct(obj: unknown): obj is Product {
  return (
    typeof obj === 'object' && obj !== null &&
    'id' in obj && typeof obj.id === 'string' &&
    'name' in obj && typeof obj.name === 'string' &&
    'price' in obj && typeof obj.price === 'number'
  );
}
```

## Enums and Unions

Prefer string literal unions over numeric enums for better type safety and simpler runtime representation.

❌ **Bad:**
```typescript
enum UserStatus {
  Active,    // 0
  Inactive,  // 1
  Pending    // 2
}
```

✅ **Good:**
```typescript
type UserStatus = 'active' | 'inactive' | 'pending';

// If enum is necessary, use const string enum:
const enum UserRole {
  Admin = "admin",
  User = "user",
  Guest = "guest"
}
```

## Generics

Use generics for reusable, type-safe functions and components.

```typescript
function identity<T>(arg: T): T {
  return arg;
}

const num = identity(123);  // number
const str = identity("hello"); // string
```

## Code Organization

### Named Exports (No Default Exports)

Named exports promote explicit imports and easier refactoring.

❌ **Bad:**
```typescript
export default class UserService { }
```

✅ **Good:**
```typescript
export class UserService { }
export const DEFAULT_USER = { };
```

### Organized Imports

Group imports: libraries → absolute paths → relative paths. Sort alphabetically.

```typescript
import React from 'react';
import { useSelector } from 'react-redux';

import { API_URL } from 'config/constants';
import { selectUser } from 'store/selectors';

import { Button } from './components/Button';
import { formatCurrency } from '../utils/formatters';
```

## Examples

**Example 1: Type guard for API response**

Input: "Validate and process API response"
Output:
```typescript
interface ApiUser {
  id: string;
  name: string;
  email: string;
}

function isApiUser(obj: unknown): obj is ApiUser {
  return (
    typeof obj === 'object' && obj !== null &&
    'id' in obj && typeof obj.id === 'string' &&
    'name' in obj && typeof obj.name === 'string' &&
    'email' in obj && typeof obj.email === 'string'
  );
}

async function fetchUser(id: string): Promise<ApiUser | null> {
  const response = await fetch(`/api/users/${id}`);
  const data: unknown = await response.json();
  
  if (isApiUser(data)) {
    return data;
  }
  return null;
}
```

**Example 2: String literal union type**

Input: "Status type with specific values"
Output:
```typescript
type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';

function updateOrderStatus(orderId: string, status: OrderStatus) {
  // TypeScript ensures only valid status values
  console.log(`Order ${orderId} -> ${status}`);
}

updateOrderStatus('123', 'shipped'); // ✅ OK
// updateOrderStatus('123', 'invalid'); // ❌ Type error
```

**Example 3: Generic utility function**

Input: "Reusable function that works with any array type"
Output:
```typescript
function getFirst<T>(items: T[]): T | undefined {
  return items[0];
}

const firstNum = getFirst([1, 2, 3]); // number | undefined
const firstStr = getFirst(['a', 'b']); // string | undefined
```

**Example 4: JSDoc types for JavaScript files**

Input: "Type-check JavaScript file with JSDoc"
Output:
```javascript
// types.d.ts
export interface UserProfile {
  id: string;
  name: string;
  email: string;
}

// user-service.js
/**
 * @typedef {import('./types').UserProfile} UserProfile
 */

/**
 * @param {UserProfile} user
 * @returns {string}
 */
export function greetUser(user) {
  return `Hello, ${user.name}!`;
}
```
Files in this package (8)
  • SKILL.md 7 KB
  • typescript.mdc 9 KB
  • typescript/SKILL.md 15 KB
  • typescript/references/advanced-patterns.md 7 KB
  • typescript/references/architecture.md 9 KB
  • typescript/references/biome.md 10 KB
  • typescript/references/performance.md 7 KB
  • typescript/references/testing.md 9 KB

Versions

RepositoryScoreLicence
This page · heyAyushh/stacc100MIT
sentimony/skills100MIT
TerminalSkills/skills100Apache-2.0
ericrisco/rsc-harness100MIT
microsoft/fast100MIT
sorah/config100MIT
claude-dev-suite/claude-dev-suite100MIT
alexander-danilenko/cortex-claude-code-plugins100MIT
EpicenterHQ/epicenter100MIT

Identical content appears in 5 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 759bc4d0611f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100typescript-best-practices
    Use when reading or writing TypeScript or JavaScript files (.ts, .tsx, .js, tsconfig.json).
  • 100typescript-patterns
    TypeScript type system patterns, generics, utility types, and strict mode best practices. Use when writing or reviewing TypeScript code.
  • 100programming-typescript
    TypeScript practices: types that match runtime guarantees, module boundaries, tsconfig and version choices. Use when writing or reviewing TypeScript code.
  • 100typescript-strict
    TypeScript strict mode patterns including schema-first development, branded types, type vs interface guidance, and tsconfig strict flags. Use when writing TypeScript code, defining types or schemas, or reviewing type safety. For immutability and pure function patterns, see the functional skill.
  • 100typescript-strict-mode
    Use when setting up a new TypeScript project, auditing an existing tsconfig.json, or reviewing code where null-reference errors or implicit any types are present.
  • 100typescript-best-practices
    TypeScript coding guidelines with dos and don'ts for type design and patterns. Use when writing, reviewing, or refactoring TypeScript code in projects with tsconfig.json or .ts/.tsx files. Trigger when the user asks to "review TypeScript code", "check my TS code", "write…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.