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': ['warn', { max: 10 }],
  'max-depth': ['warn', { max: 4 }],
  'max-lines-per-function': ['warn', { max: 50 }],
},

}, { ignores: ['dist/', 'node_modules/', '*.config.js'], } );

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": "ES2022",

// Interop
"esModuleInterop": true,
"isolatedModules": true,
"verbatimModuleSyntax": true

} }

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