{"id":12989,"library":"config-file-ts","title":"TypeScript Configuration Files","description":"config-file-ts is a JavaScript/TypeScript library that enables developers to utilize TypeScript directly for application configuration files, moving beyond the limitations of JSON or YAML. It introduces greater flexibility by supporting comments, unquoted object keys, and trailing array commas, while also allowing for programmatic logic within configs—such as variable sharing or the use of utility functions. A significant advantage is the integration with TypeScript's type system, which provides compile-time error checking and enhanced IDE support for ensuring configuration correctness. The library includes a caching mechanism for compiled TypeScript output to maintain fast parsing performance with minimal runtime overhead. The latest stable version appears to be 0.1.4, with a 0.2.8-rc1 pre-release available. Release cadence is not explicitly defined but appears infrequent based on the provided history.","status":"active","version":"0.2.8-rc1","language":"javascript","source_language":"en","source_url":"https://github.com/mighdoll/config-file-ts","tags":["javascript","typescript","config","configuration","conf","cli","cached","command","cmd"],"install":[{"cmd":"npm install config-file-ts","lang":"bash","label":"npm"},{"cmd":"yarn add config-file-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add config-file-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for runtime compilation of TypeScript configuration files. Must be available in the environment where config-file-ts is run.","package":"typescript","optional":false}],"imports":[{"note":"The primary function to load and parse a TypeScript configuration file is a named export.","wrong":"import loadTsConfig from 'config-file-ts';","symbol":"loadTsConfig","correct":"import { loadTsConfig } from 'config-file-ts';"},{"note":"For CommonJS environments, ensure you destructure the named export correctly.","wrong":"const loadTsConfig = require('config-file-ts').default;","symbol":"loadTsConfig (CommonJS)","correct":"const { loadTsConfig } = require('config-file-ts');"},{"note":"Configuration files themselves must use a default export for their main configuration object. Named exports within the config file will be ignored by `loadTsConfig`.","symbol":"Configuration file structure","correct":"export default { /* config object */ };"}],"quickstart":{"code":"import os from \"os\";\nimport { loadTsConfig } from \"config-file-ts\";\n\n// my.config.ts\nexport interface MyConfig {\n  entry?: string;\n  version?: string;\n}\n\nexport default {\n  entry: `${os.userInfo().username}'s custom stuff`,\n  version: \"1.0.0\"\n} as MyConfig;\n\n// MyProgram.ts (or main application file)\ninterface ProgramConfig {\n  entry: string;\n  version: string;\n}\n\nasync function run() {\n  try {\n    // Ensure 'my.config.ts' exists in the current directory or provide a full path\n    const config = await loadTsConfig<ProgramConfig>(\"my.config.ts\");\n    console.log(`Config loaded for user: ${config.entry}`);\n    console.log(`Application version: ${config.version}`);\n  } catch (error) {\n    console.error(\"Failed to load configuration:\", error);\n  }\n}\n\nrun();\n","lang":"typescript","description":"This quickstart demonstrates how to create a TypeScript configuration file (`my.config.ts`) with a default export, leverage Node.js modules like 'os' within it, and then load and type-check this configuration in a main application file (`MyProgram.ts`) using `loadTsConfig`."},"warnings":[{"fix":"Ensure `typescript` is installed as a dependency or peer dependency in your project: `npm install typescript` or `yarn add typescript`.","message":"The library relies on `typescript` being installed in the environment where `config-file-ts` is executed. If `typescript` is not found, `loadTsConfig` will throw an error during runtime, as it uses the TypeScript compiler API.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refactor your configuration file to ensure the primary configuration object is exported as `export default { ... }`.","message":"Configuration files loaded by `config-file-ts` must use a `export default` statement for their main configuration object. Any other exports (named exports) within the configuration file will not be picked up by `loadTsConfig`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Keep configuration files relatively simple. Ensure your `tsconfig.json` (if used for the config file) is optimized, or consider pre-compiling if startup time is critical and the config rarely changes.","message":"While `config-file-ts` caches compiled output for speed, the initial compilation of a TypeScript config file can still introduce a noticeable startup delay, especially in environments with limited resources or very complex `tsconfig.json` setups.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `typescript` as a dependency: `npm install typescript` or `yarn add typescript`.","cause":"The `typescript` package is not installed in the project's dependencies or is not resolvable in the execution environment.","error":"Error: Cannot find module 'typescript'"},{"fix":"Ensure your `.ts` config file exports its main configuration object using `export default { /* config */ };`.","cause":"The specified TypeScript configuration file does not contain a `export default` statement for its main configuration object.","error":"Error: Configuration file must have a default export."},{"fix":"Review your configuration file and the `MyConfig` interface (or similar type). Adjust either the configuration object's structure/values or the type definition to ensure they are compatible. Use `as MyConfig` in the config file to enforce the type check.","cause":"This error occurs during TypeScript compilation (either by your IDE or `tsc`) if the object exported by your configuration file does not conform to the `MyConfig` interface (or whatever type assertion you use).","error":"TS2345: Argument of type '{ /* ... */ }' is not assignable to parameter of type 'MyConfig'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}