tsconf-validator

A CLI tool to validate your TypeScript configuration files (tsconfig.json). It helps catch common configuration issues, typos, and potential problems in your TypeScript project setup.

Features

• ✅ Validates tsconfig.json files for common issues
• 🔍 Checks for non-existent paths in include, exclude, and paths
• 🚨 TS 6.0 Support: Automatically detects TS version and warns about deprecated options or default changes
• 🛠️ Best Practices: Includes recommendations for modern TypeScript setups
• 🧩 Modular Rules: Use the built-in rules or create your own
• 📦 Library support: Programmatic API to validate configs in your own tools
• 🔄 Works with multiple tsconfig.json files in monorepos
• 🚀 Zero configuration - works out of the box

Installation

npm install tsconf-validator
# or
yarn add tsconf-validator
# or
pnpm add tsconf-validator

Usage

CLI

To validate all tsconfig.json files in your project:

npx tsconf-validator

Programmatic API (Library)

You can use tsconf-validator as a library in your own tools:

import {
    validateTsConfig,
    validateTsConfigObject,
    CORE_RULES,
    ts6DeprecationRule,
} from 'tsconf-validator';

// 1. Validate a file by path
const result = validateTsConfig('./tsconfig.json');
console.log(result.errors);
console.log(result.warnings);

// 2. Validate a plain object with specific rules
const myConfig = { compilerOptions: { target: 'es5' } };
const { errors, warnings } = validateTsConfigObject(myConfig, process.cwd(), [
    ts6DeprecationRule,
    // Add other rules as needed
]);

Available Rules

The validator comes with several modular rules that can be used independently:

• ts6DeprecationRule: Checks for options deprecated in TypeScript 6.0
• ts6DefaultsRule: Warns when explicit options match defaults introduced in TypeScript 6.0
• bestPracticesRule: Recommends modern TypeScript settings (e.g., skipLibCheck: true)
• includesRule: Validates include patterns
• excludesRule: Validates exclude patterns
• rootDirRule: Validates rootDir
• pathsRule: Validates paths aliases

What It Checks

TypeScript 6.0 Migration

If your project uses TypeScript 6.0 or higher (detected via package.json), it will:

• Error on deprecated options like out, charset, target: "es5", etc.

If your project is still on TypeScript 5.x, it will:

• Warn when important defaults are omitted, such as strict, target, module, moduleResolution, and types
• Warn when explicitly setting options to values that became defaults in TypeScript 6.0, such as strict, moduleResolution, and target

Best Practices

• Recommends enabling skipLibCheck, forceConsistentCasingInFileNames, and noImplicitAny.
• Discourages disabling useful strictness checks.

include/exclude patterns

• Verifies that all patterns in the include array match at least one file/directory
• Warns about potentially problematic exclude patterns that don't match anything
• Ignores common patterns like node_modules, dist, build, etc.

Paths and Aliases

• Validates that all path aliases in compilerOptions.paths resolve to existing files/directories
• Helps catch typos in path mappings

Root Directory

• Verifies that compilerOptions.rootDir exists and is a directory
• Ensures your source directory structure is correctly configured

Exit Codes

• 0: All configurations are valid (may have warnings)
• 1: One or more configurations have errors
• 2: No tsconfig.json files found