Jiti: TypeScript and ESM Runtime for Node.js

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to use Node.js `require()` to load an ES Module (with `.mjs` or `type: module` in `package.json`) without Jiti's interop layer or proper Node.js ESM configuration.
  fix If using Jiti, ensure it's initialized and use `await jiti.import('./path/to/esm-module.mjs')`. Alternatively, enable Jiti's global loader with `node --import jiti/register`.

• SyntaxError: Cannot use import statement outside a module

  cause Running a TypeScript or ES Module file directly with `node` without Jiti's runtime transpilation or a configured Node.js ESM environment.
  fix Execute the file using `npx jiti ./your-script.ts` or `node --import jiti/register ./your-script.ts`. If programmatic, ensure `createJiti` is correctly initialized.

• TypeError: module.default is not a function/object (or: undefined is not an object)

  cause Incorrectly accessing the `default` export of a module. Some modules might not have a `default` export, or the module itself is the default export.
  fix Use `const mod = await jiti.import(id); console.log(mod?.default ?? mod);` or leverage the shorthand `const modDefault = await jiti.import(id, { default: true });` for direct default export access.

Warnings

• breaking Jiti versions `>=2.1` introduced an enhanced `interopDefault` mechanism using a new Proxy method. This change, while improving compatibility, might cause subtle behavior differences or issues for existing applications. If you migrated from `1.x` or `2.0.0` to `>=2.1` and encounter unexpected behavior, please review module interop logic.
  Fix: Thoroughly test module imports and exports after upgrading. If issues persist, consider reporting them on the Jiti GitHub repository for investigation.
• deprecated The synchronous `jiti()` API (used like `jiti('./path/to/file.ts')`) is considered deprecated. It is recommended to migrate to the asynchronous `jiti.import()` API for new code to better align with modern JavaScript module loading patterns and avoid potential blocking operations.
  Fix: Refactor synchronous `jiti(id)` calls to `await jiti.import(id)` and ensure your code handles promises appropriately.
• gotcha Using `jiti/register` for a global ESM loader hook requires Node.js version 20 or higher for full and stable compatibility.
  Fix: Ensure your Node.js environment is version 20 or newer when relying on the global ESM loader. For older Node.js versions, use `createJiti` programmatically.
• gotcha When initializing `createJiti` in a CommonJS context, the documentation marks `createJiti(__filename)` as a 'deprecated' pattern, steering users towards ESM `import { createJiti } from 'jiti'; const jiti = createJiti(import.meta.url);` as the preferred modern approach.
  Fix: For new projects, prefer setting up your project as ESM and using `import.meta.url`. If you must use CommonJS, be aware that `__filename` context might receive less future-focused support.

Install

• npm install jiti npm
• yarn add jiti yarn
• pnpm add jiti pnpm

Imports

• createJiti
  wrong:

  const { createJiti } = require('jiti');

  correct:

  import { createJiti } from 'jiti';

  While CommonJS `require` can be used, modern Jiti usage, especially for new projects, prefers ESM `import` with `import.meta.url` for context, aligning with the deprecation of `createJiti(__filename)` in the docs.
• jiti/register
  wrong:

  require('jiti/register');

  correct:

  import 'jiti/register';

  This is a side-effect import used to globally register Jiti's ESM loader hook. It requires Node.js version 20 or higher for full compatibility.
• Jiti (type)

  import type { Jiti } from 'jiti';

  Used for type-checking instances of the Jiti function when working in TypeScript projects.

Quickstart

Demonstrates how to initialize Jiti for runtime TypeScript and ESM support, dynamically import a module, access both named and default exports, and resolve paths programmatically, including creating and cleaning up a temporary module for a runnable example.

import { createJiti } from "jiti";
import path from "node:path";
import fs from "node:fs/promises";

// Initialize jiti, specifying the current module's URL for resolution context.
// In a CommonJS environment, use `__filename` instead of `import.meta.url`.
const jiti = createJiti(import.meta.url, {
  debug: process.env.NODE_ENV === 'development',
  // Cache directory to speed up subsequent loads
  cacheDir: path.join(process.cwd(), '.jiti-cache'),
});

// Example of importing a TypeScript file with ESM compatibility
// For demonstration, we'll create a dummy TS file first.
async function runJitiExample() {
  const dummyTsPath = path.join(__dirname, 'temp-module.ts');
  const dummyTsContent = 'export const message = "Hello from Jiti!"; export default { status: "OK" };';
  await fs.writeFile(dummyTsPath, dummyTsContent);

  try {
    // Import the module. Jiti handles TypeScript transpilation.
    // Use a generic type to ensure strong typing for the imported module.
    const mod = await jiti.import<{ message: string; default: { status: string } }>(dummyTsPath);
    console.log("Named export 'message':", mod.message);

    // To directly get the default export (common for default-export-only modules)
    const modDefault = await jiti.import<{ status: string }>(dummyTsPath, { default: true });
    console.log("Default export 'status':", modDefault.status);

    // Jiti can also resolve paths using ESM resolution logic.
    const resolvedPath = jiti.esmResolve('./temp-module.ts');
    console.log("Resolved path for temp-module.ts:", resolvedPath);
  } catch (error) {
    console.error("Error running Jiti example:", error);
  } finally {
    // Clean up the temporary file.
    await fs.unlink(dummyTsPath);
  }
}

runJitiExample();