get-tsconfig

^get-tsconfig

Find and parse tsconfig.json files.

Features

• Zero dependency (not even TypeScript)
• Tested against TypeScript for correctness
• Supports comments & dangling commas in tsconfig.json
• Resolves extends
• Fully typed tsconfig.json
• Validates and throws parsing errors
• Tiny! 7 kB Minified + Gzipped

^{Already a sponsor? Join the discussion in the Development repo!}

Install

npm install get-tsconfig

Why?

For TypeScript related tooling to correctly parse tsconfig.json file without depending on TypeScript.

API

getTsconfig(searchPath?, configName?, cache?, includes?)

Searches for a tsconfig file (defaults to tsconfig.json) in the searchPath and parses it. (If you already know the tsconfig path, use parseTsconfig instead). Returns null if a config file cannot be found, or an object containing the path and parsed TSConfig object if found.

Returns:

type TsconfigResult = {

    /**
     * The path to the tsconfig.json file
     */
    path: string

    /**
     * The resolved tsconfig.json file
     */
    config: TsConfigJsonResolved
}

searchPath

Type: string

Default: process.cwd()

Path to a source file or directory. The directory tree is searched up for a tsconfig.json file. Typically a TypeScript/JavaScript file path (e.g. ./src/index.ts), but a directory path also works if you don't have a specific file.

configName

Type: string

Default: tsconfig.json

The file name of the TypeScript config file.

cache

Type: Map<string, any>

Default: new Map()

Optional cache for fs operations.

includes

Type: boolean

Default: false

When true and searchPath is a file path, validates that the found tsconfig applies to the file (via files, include, and exclude). If the file isn't matched, continues searching parent directories.

By default, getTsconfig returns the nearest tsconfig — matching tsc CLI behavior (findConfigFile()). With includes, it checks the file is included by include/files and not excluded by exclude before accepting the tsconfig — matching VS Code's TypeScript Language Server behavior (isMatchedByConfig()).

Example

import { getTsconfig } from 'get-tsconfig'

// Searches for tsconfig.json starting in the current directory
console.log(getTsconfig())

// Find tsconfig.json from a TypeScript file path
console.log(getTsconfig('./path/to/index.ts'))

// Find tsconfig.json from a directory file path
console.log(getTsconfig('./path/to/directory'))

// Explicitly pass in tsconfig.json path
console.log(getTsconfig('./path/to/tsconfig.json'))

// Search for jsconfig.json - https://code.visualstudio.com/docs/languages/jsconfig
console.log(getTsconfig('.', 'jsconfig.json'))

// Find the tsconfig that actually applies to a file (Language Server behavior)
// Skips tsconfig files where the file is excluded or not included
console.log(getTsconfig('./src/index.ts', 'tsconfig.json', new Map(), true))

findTsconfig(searchPath?, configName?, cache?, includes?)

Searches for a tsconfig file by walking up the directory tree. Returns the path to the found tsconfig file, or undefined if not found.

Supports the same includes option as getTsconfig to validate that the tsconfig applies to the searchPath file.

Example

import { findTsconfig } from 'get-tsconfig'

// Find the tsconfig.json path
findTsconfig()

// Find the tsconfig that includes the file
findTsconfig('./src/index.ts', 'tsconfig.json', new Map(), true)

parseTsconfig(tsconfigPath, cache?)

Parse the tsconfig file provided. Used internally by getTsconfig. Returns the parsed tsconfig as TsConfigJsonResolved.

tsconfigPath

Type: string

Required path to the tsconfig file.

cache

Type: Map<string, any>

Default: new Map()

Optional cache for fs operations.

Example

import { parseTsconfig } from 'get-tsconfig'

// Must pass in a path to an existing tsconfig.json file
console.log(parseTsconfig('./path/to/tsconfig.custom.json'))

createFilesMatcher(tsconfig: TsconfigResult, caseSensitivePaths?: boolean)

Given a tsconfig.json file, it returns a file-matcher function that determines whether it should apply to a file path.

type FileMatcher = (filePath: string) => TsconfigResult['config'] | undefined

tsconfig

Type: TsconfigResult

Pass in the return value from getTsconfig, or a TsconfigResult object.

caseSensitivePaths

Type: boolean

By default, it uses is-fs-case-sensitive to detect whether the file-system is case-sensitive.

Pass in true to make it case-sensitive.

Example

For example, if it's called with a tsconfig.json file that has include/exclude/files defined, the file-matcher will return the config for files that match include/files, and return undefined for files that don't match or match exclude.

const tsconfig = getTsconfig()
const fileMatcher = tsconfig && createFilesMatcher(tsconfig)

/*
 * Returns tsconfig.json if it matches the file,
 * undefined if not
 */
const configForFile = fileMatcher?.('/path/to/file.ts')
const distCode = compileTypescript({
    code: sourceCode,
    tsconfig: configForFile
})

createPathsMatcher(tsconfig: TsconfigResult)

Given a tsconfig with compilerOptions.paths defined, it returns a matcher function.

The matcher function accepts an import specifier (the path to resolve), checks it against compilerOptions.paths, and returns an array of possible paths to check:

function pathsMatcher(specifier: string): string[]

This function only returns possible paths and doesn't actually do any resolution. This helps increase compatibility wtih file/build systems which usually have their own resolvers.

Example

import { getTsconfig, createPathsMatcher } from 'get-tsconfig'

const tsconfig = getTsconfig()
const pathsMatcher = createPathsMatcher(tsconfig)

const exampleResolver = (request: string) => {
    if (pathsMatcher) {
        const tryPaths = pathsMatcher(request)

        // Check if paths in `tryPaths` exist
    }
}

FAQ

How can I use TypeScript to parse tsconfig.json?

This package is a re-implementation of TypeScript's tsconfig.json parser.

However, if you already have TypeScript as a dependency, you can simply use it's API:

import {
    sys as tsSys,
    findConfigFile,
    readConfigFile,
    parseJsonConfigFileContent
} from 'typescript'

// Find tsconfig.json file
const tsconfigPath = findConfigFile(process.cwd(), tsSys.fileExists, 'tsconfig.json')

// Read tsconfig.json file
const tsconfigFile = readConfigFile(tsconfigPath, tsSys.readFile)

// Resolve extends
const parsedTsconfig = parseJsonConfigFileContent(
    tsconfigFile.config,
    tsSys,
    path.dirname(tsconfigPath)
)

Sponsors

Similar packages

Other packages similar to get-tsconfig

tsconfig-paths

The tsconfig-paths package helps resolve TypeScript paths in Node.js. It reads the paths and baseUrl options from the tsconfig.json file and configures the module resolution accordingly. Unlike get-tsconfig, which focuses on finding and reading the tsconfig.json file, tsconfig-paths is more about resolving module paths based on the TypeScript configuration.

typescript

The typescript package itself provides the TypeScript compiler and related tools, including the ability to read and parse tsconfig.json files. While it offers more comprehensive functionality for working with TypeScript, it is more complex and heavier compared to the lightweight and focused get-tsconfig package.

cosmiconfig

The cosmiconfig package is a universal configuration loader that supports various configuration file formats, including JSON, YAML, and more. It can be used to find and load configuration files like tsconfig.json, but it is more general-purpose and not specifically tailored for TypeScript configurations like get-tsconfig.