TypeScript Config File Parser

Common errors

• ERR_REQUIRE_ESM

  cause 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')

  cause 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.

  cause 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.

Warnings

• breaking tsconfck 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.
• gotcha When 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.
• gotcha The 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).
• gotcha Prior 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`.
• gotcha Early 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.

Install

• npm install tsconfck npm
• yarn add tsconfck yarn
• pnpm add tsconfck pnpm

Imports

• parse
  wrong:

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

  correct:

  import { parse } from 'tsconfck';

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

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

  correct:

  import { parseNative } from '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
  wrong:

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

  correct:

  import { find } from '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.

Quickstart

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();