tsconfck

A utility to find and parse tsconfig files without depending on typescript

Why

Because no simple official api exists and tsconfig isn't actual json.

Features

• find closest tsconfig (tsconfig.json or jsconfig.json)
• convert tsconfig to actual json and parse it
• resolve "extends"
• resolve "references" of solution-style tsconfig
• optional caching for improved performance
• optional findNative and parseNative to use official typescript api
• zero dependencies (typescript optional)
• extensive testsuite
• completely async and optimized (it's fast)
• tiny 4.8KB gzip
• unbundled esm js, no sourcemaps needed
• types generated with dts-buddy

Users

Used by vite*, vite-tsconfig-paths, astro and many more

(*) vite bundles tsconfck so it is listed as a devDependency

Install

1npm install --save-dev tsconfck # or pnpm, yarn

Usage

without typescript installed

1import { parse } from 'tsconfck';
2const {
3	tsconfigFile, // full path to found tsconfig
4	tsconfig, // tsconfig object including merged values from extended configs
5	extended, // separate unmerged results of all tsconfig files that contributed to tsconfig
6	solution, // solution result if tsconfig is part of a solution
7	referenced // referenced tsconfig results if tsconfig is a solution
8} = await parse('foo/bar.ts');

with typescript

1import { parseNative } from 'tsconfck';
2const {
3	tsconfigFile, // full path to found tsconfig
4	tsconfig, // tsconfig object including merged values from extended configs, normalized
5	result, // output of ts.parseJsonConfigFileContent
6	solution, // solution result if tsconfig is part of a solution
7	referenced // referenced tsconfig results if tsconfig is a solution
8} = await parseNative('foo/bar.ts');

API

see API-DOCS

Advanced

ignoring tsconfig for files inside node_modules

esbuild ignores node_modules so when you want to use tsconfck with esbuild, you can set ignoreNodeModules: true

1import { find, parse } from 'tsconfck';
2// returns some-lib/tsconfig.json
3const fooTSConfig = await find('node_modules/some-lib/src/foo.ts');
4
5// returns null
6const fooTSConfigIgnored = await find('node_modules/some-lib/src/foo.ts', {
7	ignoreNodeModules: true
8});
9
10// returns empty config
11const { tsconfig } = await parse('node_modules/some-lib/src/foo.ts', { ignoreNodeModules: true });

caching

a TSConfckCache instance can be created and passed to find and parse functions to reduce overhead when they are called often within the same project

1import { find, parse, TSCOnfckCache } from 'tsconfck';
2// 1. create cache instance
3const cache = new TSCOnfckCache();
4// 2. pass cache instance in options
5const fooTSConfig = await find(('src/foo.ts', { cache })); // stores tsconfig for src in cache
6const barTSConfig = await find(('src/bar.ts', { cache })); // reuses tsconfig result for src without fs call
7
8const fooResult = await parse('src/foo.ts', { cache }); // uses cached path for tsconfig, stores parse result in cache
9const barResult = await parse('src/bar.ts', { cache }); // uses cached parse result without fs call or resolving

cache invalidation

You are responsible for clearing the cache if tsconfig files are added/removed/changed after reading them during the cache lifetime.

Call cache.clear() and also discard all previous compilation results based previously cached configs.

cache mutation

Returned results are direct cache objects. If you want to modify them, deep-clone first.

cache reuse

Never use the same cache instance for mixed calls of find/findNative or parse/parseNative as result structures are different

root

This option can be used to limit finding tsconfig files outside of a root directory

1import { parse, TSConfckCache } from 'tsconfck';
2const root = '.';
3const parseOptions = { root };
4// these calls are not going to look for tsconfig files outside root
5const fooResult = await find('src/foo.ts', parseOptions);
6const barResult = await parse('src/bar.ts', parseOptions);

Using the root option can lead to errors if there is no tsconfig found inside root.

error handling

find and parse reject for errors they encounter, but return null or empty result if no config was found

If you want them to error instead, test the result and throw

1import { parse } from 'tsconfck';
2find('some/path/without/tsconfig/foo.ts').then((result) => {
3	if (result === null) {
4		throw new Error('not found');
5	}
6	return result;
7});
8parse('some/path/without/tsconfig/foo.ts').then((result) => {
9	if (result.tsconfigFile === null) {
10		throw new Error('not found');
11	}
12	return result;
13});

TSConfig type (optional, requires typescript as devDependency)

1import type { TSConfig } from 'pkg-types';

Check out https://github.com/unjs/pkg-types

cli

A simple cli wrapper is included, you can use it like this

find

1# prints /path/to/tsconfig.json on stdout
2tsconfck find src/index.ts

find-all

1# prints all tsconfig.json in dir on stdout
2tsconfck find-all src/

parse

1# print content of ParseResult.tsconfig on stdout
2tsconfck parse src/index.ts
3
4# print to file
5tsconfck parse src/index.ts > output.json

parse-result

1# print content of ParseResult on stdout
2tsconfck parse-result src/index.ts
3
4# print to file
5tsconfck parse-result src/index.ts > output.json

help

1# print usage
2tsconfck -h # or --help, -?, help

Links

• changelog

Develop

This repo uses

• pnpm
• changesets

In every PR you have to add a changeset by running pnpm changeset and following the prompts

PRs are going to be squash-merged

1# install dependencies
2pnpm install
3# run tests
4pnpm test
5#run tests in watch mode (doesn't require dev in parallel)
6pnpm test:watch

License

MIT