typescript
TypeScript language rules with strict mode, testing, linting, and CI/CD best practices
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.jsor.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:
/testsdirectory or co-located*.test.tsfiles - Coverage: Must meet project threshold (default 95%)
- Watch Mode: Use
vitestorvitest --watchfor development - CI Mode: CRITICAL - Default
npm testcommand MUST include--runflag- 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--runargument) - 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, oryarn.lock) - Workspaces: Use for monorepos
- CI/CD: Update GitHub Actions workflows to match your package manager
Dependencies
Check for latest versions:
- Use Context7 MCP tool if available
- Check npm registry:
npm view <package> versions - Review changelog for breaking changes
Dependency Guidelines:
- Use exact versions for applications (
"1.2.3") - Use semver for libraries (
"^1.2.3") - Keep dependencies updated regularly
- Use
npm auditorpnpm auditfor security - Don't use deprecated packages
- Don't add unnecessary dependencies
- Use exact versions for applications (
Type Safety
- No
any: Avoidanytype - useunknownand 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"inpackage.json - Use
.jsextensions 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.jsonfrom.gitignore - Cache Strategy: Use
cache: 'npm'insetup-nodeaction - Install Command: Use
npm ci(notnpm install) for reproducible builds
Must include GitHub Actions workflows for:
- Testing (
typescript-test.yml) - Linting (
typescript-lint.yml) - Build (
typescript-build.yml)