DOCSEARCHbyAlgolia
Submit Docs

jiti

repository·main·Indexed 25 days ago

https://github.com/unjs/jiti

Runtime TypeScript and ESM support for Node.js (v2.7.0), enabling interoperability between ESM and CommonJS. It provides a CLI for executing scripts without manual compilation and a programmatic API via createJiti for asynchronous module imports and path resolution. Features include filesystem and module caching, TypeScript paths resolution, JSX support, and a high-performance native mode via jiti/native.

Tokens
2.1K
Snippets
5
Records
19
Agent score
83%

What's inside jiti

  1. Use jiti/native for runtime native support

    main
    You can alias jiti to jiti/native to directly depend on the runtime's native import.meta.resolve and dynamic import() support. This provides the same API as jiti while easing the transition to native runtime support.

  2. Register jiti as a global ESM loader

    main

    You can globally register jiti using Node.js global hooks. This requires Node.js > 20.

    Via import:

    import "jiti/register";

    Via CLI flag:

    node --import jiti/register index.ts

  3. Configure jiti options

    main

    jiti can be configured via the options object in createJiti(url, options) or via environment variables.

    Core Options

    • debug (Boolean): Enable verbose logging. (Env: JITI_DEBUG)
    • fsCache (Boolean | String): Enable filesystem source cache for performance. Defaults to true. (Env: JITI_FS_CACHE)
    • rebuildFsCache (Boolean): Rebuild the filesystem source cache. (Env: JITI_REBUILD_FS_CACHE)
    • moduleCache (Boolean | String): Enable/disable runtime module cache. Disabling allows editing code and re-importing the same module. (Env: JITI_MODULE_CACHE)
    • interopDefault (Boolean): Combines module exports with the default export using a Proxy. Warning: This adds ~25-50ns overhead per property access. (Env: JITI_INTEROP_DEFAULT)
    • alias (Object): Custom alias map for resolving IDs. (Env: JITI_ALIAS)
    • tsconfigPaths (Boolean | String): Enable TypeScript paths resolution. true for auto-discovery, string for explicit path. (Env: JITI_TSCONFIG_PATHS)
    • jsx (Boolean | {options}): Enable JSX support via @babel/plugin-transform-react-jsx. (Env: JITI_JSX)
    • sourceMaps (Boolean): Add inline source maps to transformed source. (Env: JITI_SOURCE_MAPS)

  4. Initialize a jiti instance programmatically

    main

    To use jiti within your code, initialize an instance using createJiti. In ESM, pass import.meta.url. In CommonJS, pass __filename.

    // ESM
import { createJiti } from "jiti";
const jiti = createJiti(import.meta.url);

// CommonJS (deprecated)
const { createJiti } = require("jiti");
const jiti = createJiti(__filename);

  6. Import modules asynchronously with jiti

    main

    Use jiti.import(id) to asynchronously import modules (similar to import()) and jiti.esmResolve(id) to resolve paths (similar to import.meta.resolve()).

    To quickly get the default export of a module, use the { default: true } option.

    // jiti.import(id) is similar to import(id)
const mod = await jiti.import("./path/to/file.ts");

// jiti.esmResolve(id) is similar to import.meta.resolve(id)
const resolvedPath = jiti.esmResolve("./src");

// shortcut to mod?.default ?? mod
const modDefault = await jiti.import("./path/to/file.ts", { default: true });

  8. Configure JitiOptions

    main

    Customize the behavior of your Jiti instance using the JitiOptions object. Key options include:

    • fsCache: Enables filesystem source caching for performance. Can be a boolean or a string (custom cache directory). Default is true.
    • rebuildFsCache: Forces a rebuild of the filesystem cache. Default is false.
    • moduleCache: Integrates with Node.js native CommonJS cache. Default is true.
    • debug: Enables verbose debugging. Default is false.
    • sourceMaps: Enables sourcemaps for transformed code. Default is false.
    • interopDefault: Uses an internal Proxy to combine module exports with the default export. Default is true.
    • extensions: List of supported extensions to resolve. Default: [".js", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".json"].
    • alias: A record of path aliases.
    • tsconfigPaths: Enables tsconfig.json path resolution. Can be true (auto-discover), a string (explicit path), or false (default).
    • virtualModules: A map of module IDs to pre-loaded objects that bypass filesystem resolution.

  10. Initialize jiti with createJiti

    main
    Use createJiti to create a new jiti instance. This function is useful in pre-compiled or static environments. By default, it includes a Babel transform to handle non-standard syntax. You can provide a custom transform function in the options object if needed.

  11. Create a jiti instance with createJiti

    main
    Use createJiti to create a new instance of jiti. This instance allows you to load and transform files (such as TypeScript or ESM in a CJS environment). By default, it uses a lazy-loaded Babel transformer if no custom transform function is provided in the options.

  12. Create a high-performance jiti instance with createJiti

    main
    Use createJiti from jiti/native to create a lightweight, high-performance Jiti instance. Note that this native mode has a reduced API surface compared to the standard jiti package: jiti() (calling the function itself), jiti.resolve(), jiti.transform(), and jiti.evalModule() are not supported and will throw errors. To use the full feature set, import jiti instead of jiti/native.