Registry / serialization / cosmiconfig-typescript-loader

cosmiconfig-typescript-loader

library6.3.0jsnpmunverified

cosmiconfig-typescript-loader provides a robust TypeScript loader for `cosmiconfig`, enabling applications to load configuration files written in TypeScript (e.g., `.ts` files). It is currently at version 6.3.0, with minor and patch releases occurring as needed for dependency updates and maintenance. This package serves as a maintained successor to the abandoned `@endemolshinegroup/cosmiconfig-typescript-loader`, addressing several critical issues found in the original, such as compatibility with `cosmiconfig`'s synchronous API and providing proper TypeScript support during compilation. It leverages `jiti` for on-the-fly TypeScript compilation, supporting both CommonJS and ESM environments, making it a flexible choice for modern Node.js applications that rely on TypeScript for configuration.

serialization

npm install cosmiconfig-typescript-loader

github ↗package ↗

INSTALL

IMPORT

SIG · COSMICONFIG-TYPESC

cosmiconfig-typescript-loader

serializationjavascriptv6.3.0

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.

TypeScriptLoader

✓ import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';

✗ const { TypeScriptLoader } = require('cosmiconfig-typescript-loader');

This is the primary asynchronous loader. Use it with `await explorer.load()`. ESM import is preferred in modern Node.js.

TypeScriptLoaderSync

✓ import { TypeScriptLoaderSync } from 'cosmiconfig-typescript-loader';

✗ import TypeScriptLoaderSync from 'cosmiconfig-typescript-loader/sync';

Synchronous loader, deprecated since v6.0.0 due to Jiti's synchronous API deprecation. Only use if absolutely necessary and understand the implications.

Custom TypeScript Loader with Options

✓ import { TypeScriptLoader } from 'cosmiconfig-typescript-loader'; const customLoader = TypeScriptLoader({ cache: false });

✗ import { TypeScriptLoader } from 'cosmiconfig-typescript-loader'; const customLoader = new TypeScriptLoader();

The `TypeScriptLoader` is a factory function that returns a loader instance, not a class to be instantiated with `new`.

Demonstrates how to integrate `cosmiconfig-typescript-loader` into a `cosmiconfig` explorer to asynchronously load a TypeScript configuration file, defining its structure with an interface.

import { cosmiconfig } from "cosmiconfig"; import { TypeScriptLoader } from "cosmiconfig-typescript-loader"; interface MyConfig { host: string; port: number; enabledFeatures?: string[]; } async function loadConfig(): Promise<MyConfig | null> { const moduleName = "my-app"; const explorer = cosmiconfig(moduleName, { searchPlaces: [ `${moduleName}.config.ts`, `.${moduleName}rc.ts` ], loaders: { ".ts": TypeScriptLoader(), }, }); // Assume 'my-app.config.ts' exists in the current directory with content like: // export default { host: 'localhost', port: 3000 }; try { const result = await explorer.load(process.cwd()); if (result && result.config) { console.log("Configuration loaded successfully:", result.config); return result.config as MyConfig; } else { console.log("No configuration found."); return null; } } catch (error) { console.error("Error loading configuration:", error); throw error; } } loadConfig();

Debug

Known issues

breakingThe primary `TypeScriptLoader` export became asynchronous in version 6.0.0. If you were previously calling `explorer.load()` without `await`, your code will now produce a Promise that needs to be awaited.

fix

Update calls to `explorer.load()` to `await explorer.load()` and ensure the surrounding function is `async`.

affects: >=6.0.0

deprecatedThe `TypeScriptLoaderSync` export is deprecated since version 6.0.0. This is due to `jiti`, the underlying compilation library, deprecating its synchronous import API. While still available, its use is discouraged and it may be removed in a future major version.

fix

Migrate to the asynchronous `TypeScriptLoader` and adjust your code to use `await` with `explorer.load()`.

affects: >=6.0.0

breakingNode.js 16 support was dropped in version 6.0.0. This package now requires Node.js v18 or higher.

fix

Upgrade your Node.js runtime environment to v18 or newer.

affects: >=6.0.0

breakingVersion 5.0.0 introduced ESM support and switched from `ts-node` to `jiti` for compilation, and requires `cosmiconfig` version 8 or higher. This might affect advanced configurations or specific `tsconfig.json` setups.

fix

Ensure `cosmiconfig` is at least version 8. Review your `tsconfig.json` for any `ts-node`-specific configurations that might conflict with `jiti`'s behavior.

affects: >=5.0.0

gotchaThis package is a drop-in replacement for the unmaintained `@endemolshinegroup/cosmiconfig-typescript-loader`. If you were using the older package, you should switch to this one to receive updates and bug fixes.

fix

Uninstall `@endemolshinegroup/cosmiconfig-typescript-loader` and install `cosmiconfig-typescript-loader`.

affects: *

Errors

Common errors & fixes

Error: cosmiconfig: loader for extension ".ts" must be a function.

Attempting to use `TypeScriptLoader` or `TypeScriptLoaderSync` without calling it as a function.

fix

Ensure you call the loader, e.g., `loaders: { ".ts": TypeScriptLoader() }` instead of `loaders: { ".ts": TypeScriptLoader }`.

TypeError: explorer.load is not a function

Using `cosmiconfig-typescript-loader` with an incompatible or too old version of `cosmiconfig`.

fix

Ensure your `cosmiconfig` dependency is `^9.0.0` or higher, as required by `cosmiconfig-typescript-loader` v6.

ReferenceError: require is not defined in ES module scope

Trying to use `require()` to import `cosmiconfig-typescript-loader` in an ESM context when the package is primarily designed for ESM imports.

fix

Use `import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';` for ESM environments. If in a CJS context, you might need to enable `jiti`'s CJS fallback or ensure your project's module resolution is correctly configured.

Error: Cannot find module 'jiti'

Jiti is a peer dependency of the package and might not be explicitly installed or resolved correctly in some project setups.

fix

Manually install `jiti` as a dependency: `npm install jiti` or `yarn add jiti`.

Upgrade

Version history

6.3.0latest on npm

Audit

Dependencies

@types/nodeoptionalTypeScript type definitions for Node.js environments.

cosmiconfigrequiredCore dependency for configuration file searching and loading, required for `cosmiconfig-typescript-loader` to function.

typescriptrequiredRequired for TypeScript compilation of configuration files.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Codex-/cosmiconfig-typescript-loader ↗

packagehttps://www.npmjs.com/package/cosmiconfig-typescript-loader ↗