or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tsconfig

Resolve and parse tsconfig.json files, replicating TypeScript's behavior

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tsconfig@7.0.x

To install, run

npx @tessl/cli install tessl/npm-tsconfig@7.0.0

index.mddocs/

TSConfig

TSConfig is a TypeScript utility library for resolving and parsing tsconfig.json files, replicating TypeScript compiler behavior. It provides both synchronous and asynchronous methods for finding, resolving, loading, and parsing TypeScript configuration files with support for recursive resolution up directory trees.

Package Information

  • Package Name: tsconfig
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install tsconfig

Core Imports

import { resolve, resolveSync, find, findSync, load, loadSync, readFile, readFileSync, parse, LoadResult } from "tsconfig";

For CommonJS:

const { resolve, resolveSync, find, findSync, load, loadSync, readFile, readFileSync, parse } = require("tsconfig");

Basic Usage

import { load, loadSync } from "tsconfig";

// Asynchronous loading with recursive resolution
const result = await load(process.cwd());
console.log("Config path:", result.path);
console.log("Config:", result.config);

// Synchronous loading from specific directory
const syncResult = loadSync("/path/to/project", "custom-tsconfig.json");
console.log("Loaded config:", syncResult.config);

// Handle missing config gracefully
const fallbackResult = await load("/path/without/tsconfig");
// Returns default: { config: { files: [], compilerOptions: {} } }

Capabilities

Configuration Resolution

Resolve paths to tsconfig.json files using TypeScript's resolution algorithm.

/**
 * Resolve a configuration file, like TypeScript compiler
 * @param cwd - Current working directory to start resolution from
 * @param filename - Optional specific filename or directory to resolve
 * @returns Promise resolving to file path or void if not found
 */
function resolve(cwd: string, filename?: string): Promise<string | void>;

/**
 * Synchronous version of resolve
 * @param cwd - Current working directory to start resolution from
 * @param filename - Optional specific filename or directory to resolve
 * @returns File path or void if not found
 */
function resolveSync(cwd: string, filename?: string): string | void;

Usage Examples:

import { resolve, resolveSync } from "tsconfig";

// Find tsconfig.json recursively from current directory
const configPath = await resolve(process.cwd());

// Resolve specific config file
const specificPath = await resolve("/project/root", "tsconfig.build.json");

// Resolve config in specific directory
const dirPath = await resolve("/project/root", "configs");

// Synchronous resolution
const syncPath = resolveSync(process.cwd());

Recursive Configuration Discovery

Find tsconfig.json files by recursively searching up the directory tree.

/**
 * Recursively find tsconfig.json upward from directory
 * @param dir - Directory to start search from
 * @returns Promise resolving to file path or void if not found
 */
function find(dir: string): Promise<string | void>;

/**
 * Synchronous version of find
 * @param dir - Directory to start search from
 * @returns File path or void if not found
 */
function findSync(dir: string): string | void;

Usage Examples:

import { find, findSync } from "tsconfig";

// Find tsconfig.json starting from current directory
const found = await find(process.cwd());

// Find from specific directory
const projectConfig = await find("/deep/nested/project/path");

// Synchronous find
const syncFound = findSync(__dirname);

Configuration Loading and Parsing

Load and parse tsconfig.json files with comprehensive error handling.

/**
 * Resolve, load and parse tsconfig.json
 * @param cwd - Current working directory to start resolution from
 * @param filename - Optional specific filename or directory to resolve
 * @returns Promise resolving to LoadResult with path and parsed config
 */
function load(cwd: string, filename?: string): Promise<LoadResult>;

/**
 * Synchronous version of load
 * @param cwd - Current working directory to start resolution from
 * @param filename - Optional specific filename or directory to resolve
 * @returns LoadResult with path and parsed config
 */
function loadSync(cwd: string, filename?: string): LoadResult;

/**
 * Read and parse tsconfig.json file contents
 * @param filename - Path to file to read
 * @returns Promise resolving to parsed JSON config
 */
function readFile(filename: string): Promise<any>;

/**
 * Synchronous version of readFile
 * @param filename - Path to file to read
 * @returns Parsed JSON config
 */
function readFileSync(filename: string): any;

/**
 * Parse tsconfig.json file contents string
 * @param contents - Raw file contents to parse
 * @param filename - Filename for error reporting
 * @returns Parsed JSON object
 */
function parse(contents: string, filename: string): any;

Usage Examples:

import { load, loadSync, readFile, readFileSync, parse } from "tsconfig";

// Load with automatic resolution
const result = await load(process.cwd());
if (result.path) {
  console.log(`Loaded from: ${result.path}`);
  console.log(`Compiler options:`, result.config.compilerOptions);
}

// Load specific config file
const buildConfig = await load("/project", "tsconfig.build.json");

// Direct file reading
const config = await readFile("/path/to/tsconfig.json");

// Parse raw content
const rawContent = `{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs"
  }
}`;
const parsed = parse(rawContent, "tsconfig.json");

Types

/**
 * Result type for load operations
 */
interface LoadResult {
  /** Optional path to the resolved tsconfig file */
  path?: string;
  /** Parsed configuration object */
  config: any;
}

Error Handling

The library throws TypeError instances for common error conditions:

  • Non-existent paths: "The specified path does not exist: <filename>"
  • Missing configs: "Cannot find a tsconfig.json file at the specified directory: ${filename}"
  • Invalid JSON: Standard JSON parsing errors from malformed configuration files

Default Behavior

When no tsconfig.json file is found, load and loadSync return a default configuration:

{
  path: undefined,
  config: {
    files: [],
    compilerOptions: {}
  }
}

Advanced Features

BOM and Comment Handling

The library automatically handles:

  • UTF-8 BOM removal: Strips byte order marks from file contents
  • JSON comment support: Removes // and /* */ style comments from configuration files
  • Empty file support: Gracefully handles completely empty tsconfig.json files

TypeScript Compiler Compatibility

TSConfig replicates the exact resolution behavior of the TypeScript compiler:

  • Recursive upward directory traversal
  • Support for both file and directory targets
  • Consistent error handling and messaging
  • Standard tsconfig.json filename convention