Cosmiconfig TypeScript Loader

Common errors

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

  cause 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

  cause 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

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

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

Warnings

• breaking The 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`.
• deprecated The `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()`.
• breaking Node.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.
• breaking Version 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.
• gotcha This 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`.

Install

• npm install cosmiconfig-typescript-loader npm
• yarn add cosmiconfig-typescript-loader yarn
• pnpm add cosmiconfig-typescript-loader pnpm

Imports

• TypeScriptLoader
  wrong:

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

  correct:

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

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

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

  correct:

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

  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
  wrong:

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

  correct:

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

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

Quickstart

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