{"id":12192,"library":"tsconfck","title":"TypeScript Config File Parser","description":"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.","status":"active","version":"3.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/dominikg/tsconfck","tags":["javascript","typescript","tsconfig","tsconfig.json","jsconfig","jsconfig.json"],"install":[{"cmd":"npm install tsconfck","lang":"bash","label":"npm"},{"cmd":"yarn add tsconfck","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsconfck","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for 'parseNative' function, or if using specific TypeScript features like its native config parsing APIs.","package":"typescript","optional":true}],"imports":[{"note":"Primary function for parsing tsconfig files without `typescript` installed. `tsconfck` is an ESM-only package.","wrong":"const { parse } = require('tsconfck');","symbol":"parse","correct":"import { parse } from 'tsconfck';"},{"note":"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.","wrong":"const { parseNative } = require('tsconfck');","symbol":"parseNative","correct":"import { parseNative } from 'tsconfck';"},{"note":"Utility to locate the closest tsconfig.json or jsconfig.json file from a given path. tsconfck is an ESM-only package.","wrong":"const { find } = require('tsconfck');","symbol":"find","correct":"import { find } from 'tsconfck';"},{"note":"Class for creating a cache instance to improve performance when calling `find` or `parse` repeatedly.","symbol":"TSCOnfckCache","correct":"import { TSCOnfckCache } from 'tsconfck';"}],"quickstart":{"code":"import { parse } from 'tsconfck';\nimport * as path from 'path';\nimport * as fs from 'fs/promises';\n\n// Create a dummy tsconfig.json for demonstration\nconst projectRoot = path.join(process.cwd(), 'temp_tsconfck_project');\nconst tsconfigFile = path.join(projectRoot, 'tsconfig.json');\n\nasync function setupProject() {\n  await fs.mkdir(projectRoot, { recursive: true });\n  await fs.writeFile(tsconfigFile, JSON.stringify({\n    \"compilerOptions\": {\n      \"target\": \"es2020\",\n      \"module\": \"esnext\",\n      \"strict\": true,\n      \"esModuleInterop\": true,\n      \"forceConsistentCasingInFileNames\": true,\n      \"skipLibCheck\": true\n    },\n    \"include\": [\n      \"src/**/*.ts\"\n    ]\n  }, null, 2));\n  await fs.mkdir(path.join(projectRoot, 'src'), { recursive: true });\n  await fs.writeFile(path.join(projectRoot, 'src', 'index.ts'), 'console.log(\"Hello\");');\n}\n\nasync function cleanupProject() {\n  await fs.rm(projectRoot, { recursive: true, force: true });\n}\n\nasync function run() {\n  await setupProject();\n  try {\n    const { tsconfigFile, tsconfig, extended, solution, referenced } = await parse(path.join(projectRoot, 'src', 'index.ts'));\n\n    console.log('Found tsconfig file:', tsconfigFile);\n    console.log('Parsed tsconfig (merged):', tsconfig);\n    // console.log('Extended configs:', extended);\n    // console.log('Solution config:', solution);\n    // console.log('Referenced configs:', referenced);\n  } catch (error) {\n    console.error('Error parsing tsconfig:', error);\n  } finally {\n    await cleanupProject();\n  }\n}\n\nrun();","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your project to use ES modules, or dynamically import `tsconfck` using `await import('tsconfck')` if you must remain in a CommonJS context.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0 <3.1.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0 <3.1.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to `require()` tsconfck in a CommonJS module, but tsconfck is an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Install `typescript` as a peer dependency: `npm install typescript@^5.0.0` or use the `parse` function instead, which does not require `typescript`.","cause":"The `parseNative` function was called, but the `typescript` peer dependency is either not installed or not found.","error":"TypeError: Cannot read properties of undefined (reading 'parseJsonConfigFileContent')"},{"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.","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.","error":"The tsconfig content did not seem to be a valid tsconfig (eg. comments outside of strings) or could not be parsed as json."}],"ecosystem":"npm"}