typescript

hivellm's avatarfrom hivellm

TypeScript language rules with strict mode, testing, linting, and CI/CD best practices

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 10, 2025

When & Why to Use This Skill

This TypeScript skill establishes a high-standard development environment by enforcing strict mode, comprehensive testing with Vitest, and automated linting. It optimizes the software development lifecycle (SDLC) by providing standardized configurations for ESLint, Prettier, and TypeScript 5.3+, ensuring enterprise-grade code quality and seamless CI/CD integration.

Use Cases

  • Project Initialization: Rapidly set up new TypeScript projects with industry-standard strict configurations, directory structures, and essential configuration files (tsconfig, eslint, prettier).
  • Automated Quality Assurance: Execute a complete quality check sequence including type-checking, linting, and formatting to ensure 0 warnings and prevent CI/CD pipeline failures.
  • Testing & Coverage: Implement robust unit and integration testing using Vitest with a mandatory 95% coverage threshold and CI-optimized execution commands.
  • Type Safety Enforcement: Transition from loose JavaScript to strict TypeScript by enforcing 'no-any' policies, type guards, and custom error handling patterns for more maintainable code.
  • CI/CD Optimization: Align local development workflows with GitHub Actions using specific 'npm ci' and caching strategies to ensure reproducible builds and faster deployment cycles.
name"TypeScript"
description"TypeScript language rules with strict mode, testing, linting, and CI/CD best practices"
version"1.0.0"
category"languages"
author"Rulebook"
tags["typescript", "javascript", "node", "strict", "testing", "vitest", "eslint"]
dependencies[]
conflicts[]

TypeScript Project Rules

Agent Automation Commands

CRITICAL: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

# Complete quality check sequence:
npm run type-check        # Type checking
npm run lint              # Linting (0 warnings required)
npm run format            # Code formatting
npm test                  # All tests (100% pass required)
npm run test:coverage     # Coverage check (95%+ required)
npm run build             # Build verification

# Security audit:
npm audit --production    # Vulnerability scan
npm outdated              # Check outdated deps (informational)

TypeScript Configuration

CRITICAL: Use TypeScript 5.3+ with strict mode enabled.

  • Version: TypeScript 5.3+
  • Mode: Strict mode enabled
  • Target: ES2022 or later
  • Module: ESNext with Node16 module resolution

tsconfig.json Requirements

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Code Quality Standards

Mandatory Quality Checks

CRITICAL: After implementing ANY feature, you MUST run these commands in order.

IMPORTANT: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!

# Pre-Commit Checklist (MUST match .github/workflows/*.yml)

# 1. Type check (matches workflow)
npm run type-check  # or: tsc --noEmit

# 2. Lint (MUST pass with no warnings - matches workflow)
npm run lint

# 3. Format check (matches workflow - use same command as CI)
npx prettier --check 'src/**/*.ts' 'tests/**/*.ts'

# 4. Run all tests (MUST pass 100% - matches workflow)
npm test

# 5. Build (MUST succeed - matches workflow)
npm run build

# 6. Check coverage (MUST meet threshold)
npm run test:coverage

If ANY of these fail, you MUST fix the issues before committing.

Linting

  • Use ESLint with TypeScript plugin
  • Configuration in eslint.config.js or .eslintrc.json
  • Must pass with no warnings: eslint src/**/*.ts
  • Fix automatically when possible: eslint src/**/*.ts --fix

Example ESLint config:

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "warn"
  }
}

Formatting

  • Use Prettier for code formatting
  • Configuration in .prettierrc.json
  • Integrate with ESLint for consistency
  • Format before committing: prettier --write "src/**/*.ts"

Example Prettier config:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

Testing

  • Framework: Vitest (recommended) or Jest
  • Location: /tests directory or co-located *.test.ts files
  • Coverage: Must meet project threshold (default 95%)
  • Watch Mode: Use vitest or vitest --watch for development
  • CI Mode: CRITICAL - Default npm test command MUST include --run flag
    • This prevents Vitest from entering watch mode, which never terminates
    • In package.json: "test": "vitest --run"
    • In CI workflows: use npm test (do NOT add --run argument)
    • For manual development, use npm run test:watch

Example test structure:

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { myFunction } from './my-module';

describe('myFunction', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  it('should handle valid input', () => {
    const result = myFunction('input');
    expect(result).toBe('expected');
  });

  it('should throw on invalid input', () => {
    expect(() => myFunction('')).toThrow('Invalid input');
  });
});

Package Management

CRITICAL: Use consistent package manager across team.

  • Default: npm (most compatible, built-in)
  • Alternative: pnpm (fast, disk-efficient) or yarn
  • Lockfile: Always commit lockfile (package-lock.json, pnpm-lock.yaml, or yarn.lock)
  • Workspaces: Use for monorepos
  • CI/CD: Update GitHub Actions workflows to match your package manager

Dependencies

  1. Check for latest versions:

    • Use Context7 MCP tool if available
    • Check npm registry: npm view <package> versions
    • Review changelog for breaking changes
  2. Dependency Guidelines:

    • Use exact versions for applications ("1.2.3")
    • Use semver for libraries ("^1.2.3")
    • Keep dependencies updated regularly
    • Use npm audit or pnpm audit for security
    • Don't use deprecated packages
    • Don't add unnecessary dependencies

Type Safety

  • No any: Avoid any type - use unknown and type guards
  • Strict null checks: Handle null/undefined explicitly
  • Type assertions: Minimize use of as - prefer type guards
  • Generics: Use for reusable type-safe code

Example type-safe code:

// Good: Type guard
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function process(input: unknown): string {
  if (isString(input)) {
    return input.toUpperCase();
  }
  throw new Error('Invalid input');
}

// Bad: Type assertion
function processUnsafe(input: unknown): string {
  return (input as string).toUpperCase(); // Runtime error if not string
}

Error Handling

  • Create custom error classes
  • Use type guards for error checking
  • Document errors in JSDoc/TSDoc
  • Never swallow errors silently

Example:

export class ValidationError extends Error {
  constructor(
    message: string,
    public readonly field: string
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

export function validate(data: unknown): Data {
  if (!isValidData(data)) {
    throw new ValidationError('Invalid data structure', 'data');
  }
  return data;
}

Project Structure

project/
├── package.json        # Package manifest
├── tsconfig.json       # TypeScript config
├── vitest.config.ts    # Test config
├── README.md           # Project overview
├── CHANGELOG.md        # Version history
├── AGENTS.md           # AI assistant rules
├── src/
│   ├── index.ts        # Main entry point
│   ├── types.ts        # Type definitions
│   └── ...
├── tests/              # Test files
├── dist/               # Compiled output (gitignored)
└── docs/               # Project documentation

Module System

  • Use ES modules (import/export)
  • Set "type": "module" in package.json
  • Use .js extensions in imports for Node.js compatibility
  • Configure moduleResolution: "node" in tsconfig.json

Example:

// Good: ES modules with .js extension
import { myFunction } from './my-module.js';

export { myFunction };
export default class MyClass {}

CI/CD Requirements

CRITICAL: GitHub Actions cache: 'npm' requires package-lock.json to be committed.

  • Lockfile Requirement: Remove package-lock.json from .gitignore
  • Cache Strategy: Use cache: 'npm' in setup-node action
  • Install Command: Use npm ci (not npm install) for reproducible builds

Must include GitHub Actions workflows for:

  1. Testing (typescript-test.yml)
  2. Linting (typescript-lint.yml)
  3. Build (typescript-build.yml)