tsconfck

library3.1.6jsnpmunverified

tsconfck is a robust utility designed to find and parse `tsconfig.json` or `jsconfig.json` files programmatically, abstracting away the complexities of TypeScript's native parsing mechanisms. It enables developers to work with TypeScript configuration files without requiring a direct dependency on the `typescript` package itself, offering a lightweight alternative. The current stable version is 3.1.6, with a release cadence that appears to be frequent patch releases addressing bug fixes and minor improvements, as seen in the recent changelog for 3.1.x. Key differentiators include its ability to resolve `extends` and `references` properties, optional caching for performance, a minimal bundle size (4.8KB gzip), and being completely asynchronous. It also offers `parseNative` for when the `typescript` peer dependency *is* present and desired for official API usage. It's notably used by popular tools like Vite and Astro for their configuration needs.

serialization devops

npm install tsconfck

github ↗package ↗

INSTALL

IMPORT

SIG · TSCONFCK

tsconfck

serializationjavascriptv3.1.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'tsconfck';

✗ const { parse } = require('tsconfck');

Primary function for parsing tsconfig files without `typescript` installed. `tsconfck` is an ESM-only package.

parseNative

✓ import { parseNative } from 'tsconfck';

✗ const { parseNative } = require('tsconfck');

Use this function if you have `typescript` installed as a peer dependency and want to leverage its official API for parsing. tsconfck is an ESM-only package.

find

✓ import { find } from 'tsconfck';

✗ const { find } = require('tsconfck');

Utility to locate the closest tsconfig.json or jsconfig.json file from a given path. tsconfck is an ESM-only package.

TSCOnfckCache

✓ import { TSCOnfckCache } from 'tsconfck';

Class for creating a cache instance to improve performance when calling `find` or `parse` repeatedly.

This example demonstrates how to find and parse a tsconfig.json file using the `parse` function from `tsconfck` based on a source file path. It creates a temporary project structure, parses its config, and then cleans up.

import { parse } from 'tsconfck'; import * as path from 'path'; import * as fs from 'fs/promises'; // Create a dummy tsconfig.json for demonstration const projectRoot = path.join(process.cwd(), 'temp_tsconfck_project'); const tsconfigFile = path.join(projectRoot, 'tsconfig.json'); async function setupProject() { await fs.mkdir(projectRoot, { recursive: true }); await fs.writeFile(tsconfigFile, JSON.stringify({ "compilerOptions": { "target": "es2020", "module": "esnext", "strict": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "skipLibCheck": true }, "include": [ "src/**/*.ts" ] }, null, 2)); await fs.mkdir(path.join(projectRoot, 'src'), { recursive: true }); await fs.writeFile(path.join(projectRoot, 'src', 'index.ts'), 'console.log("Hello");'); } async function cleanupProject() { await fs.rm(projectRoot, { recursive: true, force: true }); } async function run() { await setupProject(); try { const { tsconfigFile, tsconfig, extended, solution, referenced } = await parse(path.join(projectRoot, 'src', 'index.ts')); console.log('Found tsconfig file:', tsconfigFile); console.log('Parsed tsconfig (merged):', tsconfig); // console.log('Extended configs:', extended); // console.log('Solution config:', solution); // console.log('Referenced configs:', referenced); } catch (error) { console.error('Error parsing tsconfig:', error); } finally { await cleanupProject(); } } run();

Debug

Known issues

breakingtsconfck is an ESM-only package since its major version 3. This means it can only be imported using `import` statements and cannot be `require`d in CommonJS environments without specific workarounds like dynamic import or setting 'type': 'module' in your package.json.

fix

Migrate your project to use ES modules, or dynamically import `tsconfck` using `await import('tsconfck')` if you must remain in a CommonJS context.

affects: >=3.0.0

gotchaWhen using the `parseNative` function, a `typescript` peer dependency (version ^5.0.0) is required. If `typescript` is not installed or the version is incompatible, `parseNative` will not function as expected or may throw errors.

fix

Ensure `typescript` is installed as a peer dependency with a compatible version (e.g., `npm install typescript@^5.0.0` or `pnpm add typescript@^5.0.0`). For parsing without `typescript`, use the `parse` function instead.

affects: >=3.0.0

gotchaThe package provides caching capabilities via `TSCOnfckCache`, but cache invalidation is explicitly stated to be the user's responsibility. Failing to clear the cache when `tsconfig` files are added, removed, or changed will lead to stale configuration data being used.

fix

Implement explicit cache invalidation logic, such as calling `cache.clear()` when configuration files are known to have changed (e.g., on file watch events, before a build starts).

affects: >=3.0.0

gotchaPrior to version 3.1.4, glob matching for `include`/`exclude` patterns might not have correctly handled paths without explicit extensions or wildcards (e.g., `src` incorrectly becoming `src/**/*`). This could lead to files not being included/excluded as expected.

fix

Upgrade to `tsconfck@3.1.4` or newer to ensure correct glob matching behavior. If upgrading is not possible, explicitly add `/**/*` to such path patterns in your `tsconfig.json`.

affects: >=3.0.0 <3.1.4

gotchaEarly 3.x versions had issues resolving `${configDir}` in referenced tsconfig files and handling complex `extends` scenarios (e.g., `extends: '..'`). This could lead to incorrect configuration resolution in multi-package repositories or complex project setups.

fix

Upgrade to `tsconfck@3.1.5` or newer to get fixes for `${configDir}` resolution in referenced files. For `extends: '..'` edge cases, version 3.1.6 contains specific fixes.

affects: >=3.0.0 <3.1.5

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` tsconfck in a CommonJS module, but tsconfck is an ESM-only package.

fix

Change your import statement to `import { parse } from 'tsconfck';` and ensure your environment supports ES modules (e.g., `type: 'module'` in package.json or running with a modern Node.js version).

TypeError: Cannot read properties of undefined (reading 'parseJsonConfigFileContent')

The `parseNative` function was called, but the `typescript` peer dependency is either not installed or not found.

fix

Install `typescript` as a peer dependency: `npm install typescript@^5.0.0` or use the `parse` function instead, which does not require `typescript`.

The tsconfig content did not seem to be a valid tsconfig (eg. comments outside of strings) or could not be parsed as json.

The `tsconfig.json` file contains invalid JSON syntax, such as trailing commas in strict JSON mode, or unquoted keys/values. While `tsconfig.json` tolerates comments, strict JSON parsing might fail.

fix

Verify your `tsconfig.json` for syntax errors. Use a JSON linter or validator to ensure it's valid JSON. If the error persists, it might indicate an issue with how `tsconfck` handles specific non-standard JSON constructs in older versions.

Upgrade

Version history

3.1.6latest on npm

Audit

Dependencies

typescriptoptionalPeer dependency required for 'parseNative' function, or if using specific TypeScript features like its native config parsing APIs.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dominikg/tsconfck ↗

packagehttps://www.npmjs.com/package/tsconfck ↗