Registry / serialization / config-file-ts

config-file-ts

library0.2.8-rc1jsnpmunverified

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.

serialization

npm install config-file-ts

github ↗package ↗

INSTALL

IMPORT

SIG · CONFIG-FILE-TS

config-file-ts

serializationjavascriptv0.2.8-rc1

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.

loadTsConfig

✓ import { loadTsConfig } from 'config-file-ts';

✗ import loadTsConfig from 'config-file-ts';

The primary function to load and parse a TypeScript configuration file is a named export.

loadTsConfig (CommonJS)

✓ const { loadTsConfig } = require('config-file-ts');

✗ const loadTsConfig = require('config-file-ts').default;

For CommonJS environments, ensure you destructure the named export correctly.

Configuration file structure

✓ export default { /* config object */ };

Configuration files themselves must use a default export for their main configuration object. Named exports within the config file will be ignored by `loadTsConfig`.

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

import os from "os"; import { loadTsConfig } from "config-file-ts"; // my.config.ts export interface MyConfig { entry?: string; version?: string; } export default { entry: `${os.userInfo().username}'s custom stuff`, version: "1.0.0" } as MyConfig; // MyProgram.ts (or main application file) interface ProgramConfig { entry: string; version: string; } async function run() { try { // Ensure 'my.config.ts' exists in the current directory or provide a full path const config = await loadTsConfig<ProgramConfig>("my.config.ts"); console.log(`Config loaded for user: ${config.entry}`); console.log(`Application version: ${config.version}`); } catch (error) { console.error("Failed to load configuration:", error); } } run();

Debug

Known issues

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

fix

Ensure `typescript` is installed as a dependency or peer dependency in your project: `npm install typescript` or `yarn add typescript`.

affects: >=0.1.0

gotchaConfiguration 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`.

fix

Refactor your configuration file to ensure the primary configuration object is exported as `export default { ... }`.

affects: >=0.1.0

gotchaWhile `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.

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.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'typescript'

The `typescript` package is not installed in the project's dependencies or is not resolvable in the execution environment.

fix

Install `typescript` as a dependency: `npm install typescript` or `yarn add typescript`.

Error: Configuration file must have a default export.

The specified TypeScript configuration file does not contain a `export default` statement for its main configuration object.

fix

Ensure your `.ts` config file exports its main configuration object using `export default { /* config */ };`.

TS2345: Argument of type '{ /* ... */ }' is not assignable to parameter of type 'MyConfig'.

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

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.

Upgrade

Version history

0.2.8-rc1latest on npm

Audit

Dependencies

typescriptrequiredRequired for runtime compilation of TypeScript configuration files. Must be available in the environment where config-file-ts is run.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mighdoll/config-file-ts ↗

packagehttps://www.npmjs.com/package/config-file-ts ↗