typescript-quality

name	typescript-quality
description	| Use when this capability is needed.

TypeScript Quality - Quick Reference

When NOT to Use This Skill

• SonarQube integration - Use sonarqube skill
• Test configuration - Use vitest skill
• Security scanning - Use security skills
• React-specific patterns - Use react skill

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: typescript or biome for comprehensive documentation.

Tool Comparison

Tool	Speed	Type-aware	Configuration
Biome	Fastest	No	Minimal
ESLint	Slower	Yes (with TS)	Extensive
TypeScript	N/A	Yes	tsconfig.json

Recommendation: Use Biome for formatting + basic linting, ESLint for type-aware rules.

Biome Setup (Recommended)

Installation

npm install -D @biomejs/biome
npx biome init

biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": { "maxAllowedComplexity": 15 }
        }
      },
      "suspicious": {
        "noExplicitAny": "error",
        "noImplicitAnyLet": "error"
      },
      "style": {
        "noNonNullAssertion": "warn",
        "useConst": "error"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  }
}

Commands

# Check all
npx biome check .

# Fix auto-fixable
npx biome check --write .

# Format only
npx biome format --write .

# Lint only
npx biome lint .

# CI mode (no write)
npx biome ci .

ESLint Setup (Type-aware)

Installation

npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

eslint.config.js (Flat Config - ESLint 9+)

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Type safety
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-unsafe-assignment': 'error',
      '@typescript-eslint/no-unsafe-call': 'error',
      '@typescript-eslint/no-unsafe-member-access': 'error',
      '@typescript-eslint/no-unsafe-return': 'error',

      // Best practices
      '@typescript-eslint/explicit-function-return-type': 'warn',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/no-misused-promises': 'error',

      // Code quality
      'complexity': [, { :  }],
      : [, { :  }],
      : [, { :  }],
    },
  },
  {
    : [, , ],
  }
);

Commands

# Lint
npx eslint .

# Fix auto-fixable
npx eslint --fix .

# Show rule details
npx eslint --print-config src/index.ts

TypeScript Strict Mode

tsconfig.json (Maximum Strictness)

{
  "compilerOptions": {
    // Strict type checking
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,

    // Additional checks
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,

    // Module resolution
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": 

    
     
     
     
  

Key Strict Flags Explained

Flag	Effect	Example
noUncheckedIndexedAccess	Array access returns T | undefined	arr[0] is T | undefined
exactOptionalPropertyTypes	{ a?: string } means string or missing, not undefined	Can't assign undefined explicitly
noPropertyAccessFromIndexSignature	Forces bracket notation for index signatures	obj['key'] not obj.key

Common Code Smells & Fixes

1. Excessive any Usage

// BAD
function process(data: any): any {
  return data.value;
}

// GOOD
interface DataItem {
  value: string;
}

function process(data: DataItem): string {
  return data.value;
}

// GOOD - When truly unknown
function process(data: unknown): string {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    return String((data as { value: unknown }).value);
  }
  throw new Error('Invalid data');
}

2. Type Assertions Overuse

// BAD
const user = response.data as User;

// GOOD - Use type guards
function isUser(data: unknown): data is User {
  return (
    typeof data === 'object' &&
    data !== null &&
    'id' in data &&
    'email' in data
  );
}

if (isUser(response.data)) {
  // response.data is User here
}

// GOOD - Use Zod for runtime validation
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
});

const user = UserSchema.parse(response.data);

3. Non-null Assertion

// BAD
const element = document.getElementById('app')!;

// GOOD
const element = document.getElementById('app');
if (!element) {
  throw new Error('App element not found');
}

// GOOD - Optional chaining when appropriate
const value = element?.textContent ?? 'default';

4. Complex Conditionals

// BAD
if (user && user.isActive && user.role === 'admin' && !user.suspended) {
  // ...
}

// GOOD - Extract to function
function canAccessAdmin(user: User | null): user is User {
  return (
    user !== null &&
    user.isActive &&
    user.role === 'admin' &&
    !user.suspended
  );
}

if (canAccessAdmin(user)) {
  // ...
}

5. Long Functions

// BAD - 100+ line function
async function processOrder(order: Order) {
  // validation
  // calculation
  // database operations
  // notifications
  // logging
}

// GOOD - Split responsibilities
async function processOrder(order: Order) {
  validateOrder(order);
  const total = calculateTotal(order);
  await saveOrder(order, total);
  await notifyUser(order);
  logOrderProcessed(order);
}

Pre-commit Setup

package.json Scripts

{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "typecheck": "tsc --noEmit",
    "quality": "npm run typecheck && npm run lint"
  }
}

Husky + lint-staged

npm install -D husky lint-staged
npx husky init

// package.json
{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

# .husky/pre-commit
npx lint-staged

VS Code Settings

// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "quickfix.biome": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Quality Metrics Targets

Metric	Target	Tool
Cyclomatic Complexity	< 10	ESLint complexity rule
Cognitive Complexity	< 15	Biome/SonarQube
Function Length	< 50 lines	ESLint max-lines-per-function
File Length	< 300 lines	ESLint max-lines
Nesting Depth	< 4 levels	ESLint max-depth
Parameters	< 4	ESLint max-params

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
any everywhere	Defeats type safety	Use proper types or unknown
as type assertions	Runtime errors	Use type guards or Zod
! non-null assertion	Potential runtime null	Proper null checking
Disabling lint rules inline	Technical debt	Fix the issue or configure globally
@ts-ignore	Hides real errors	Use @ts-expect-error with comment
No strict mode	Weaker guarantees	Enable all strict flags

Quick Troubleshooting

Issue	Likely Cause	Solution
ESLint slow on large projects	Type-aware rules expensive	Use project references, cache
Biome conflicts with ESLint	Both trying to format	Use Biome for format, ESLint for type rules
TypeScript error not caught by lint	Need type-aware rule	Use typescript-eslint with projectService
Import order inconsistent	No auto-organize	Enable Biome organizeImports
Pre-commit too slow	Running on all files	Use lint-staged for changed files only

Related Skills

• Biome
• ESLint
• SonarQube
• Clean Code

---

Source: claude-dev-suite/claude-dev-suite — distributed by TomeVault.