jiti

This is the active development branch. Check out jiti/v1 for legacy v1 docs and code.

🌟 Used in

Docusaurus, ESLint, FormKit, Histoire, Knip, Nitro, Nuxt, PostCSS loader, Rsbuild, Size Limit, Slidev, Tailwindcss, Tokenami, UnoCSS, WXT, Winglang, Graphql code generator, Lingui, Scaffdog, Storybook, ...UnJS ecosystem, ...60M+ npm monthly downloads, ...6M+ public repositories.

✅ Features

• Seamless TypeScript and ESM syntax support for Node.js
• Seamless interoperability between ESM and CommonJS
• Asynchronous API to replace import()
• Synchronous API to replace require() (deprecated)
• Super slim and zero dependency
• Custom resolve aliases
• Smart syntax detection to avoid extra transforms
• Node.js native require.cache integration
• Filesystem transpile with hard disk caches
• ESM Loader support
• JSX support (opt-in)

[!IMPORTANT] To enhance npm compatibility with the introduction of native ESM, jiti >=2.1 enabled interopdefault using a new Proxy. This may cause behavior changes, especially if you migrated to 2.0.0 earlier.

💡 Usage

CLI

You can use jiti CLI to quickly run any script with TypeScript and native ESM support!

npx jiti ./index.ts

Programmatic

Initialize a jiti instance:

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

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

Import (async) and resolve with ESM compatibility:

// 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");

If you need the default export of module, you can use jiti.import(id, { default: true }) as shortcut to mod.default ?? mod.

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

CommonJS (sync & deprecated):

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

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

You can also pass options as the second argument:

const jiti = createJiti(import.meta.url, { debug: true });

Register global ESM loader

You can globally register jiti using global hooks. (Important: Requires Node.js > 20)

import "jiti/register";

Or:

node --import jiti/register index.ts

🎈 jiti/native

You can alias jiti to jiti/native to directly depend on runtime's import.meta.resolve and dynamic import() support. This allows easing up the ecosystem transition to runtime native support by giving the same API of jiti.

⚙️ Options

debug

• Type: Boolean
• Default: false
• Environment variable: JITI_DEBUG

Enable verbose logging. You can use JITI_DEBUG=1 <your command> to enable it.

fsCache

• Type: Boolean | String
• Default: true
• Environment variable: JITI_FS_CACHE

Filesystem source cache (enabled by default)

By default (when is true), jiti uses node_modules/.cache/jiti (if exists) or {TMP_DIR}/jiti.

Note: It is recommended that this option be enabled for better performance.

moduleCache

• Type: String
• Default: true
• Environment variable: JITI_MODULE_CACHE

Runtime module cache (enabled by default).

Disabling allows editing code and importing the same module multiple times.

When enabled, jiti integrates with Node.js native CommonJS cache-store.

transform

• Type: Function
• Default: Babel (lazy loaded)

Transform function. See src/babel for more details

sourceMaps

• Type: Boolean
• Default false
• Environment variable: JITI_SOURCE_MAPS

Add inline source map to transformed source for better debugging.

interopDefault

• Type: Boolean
• Default: true
• Environment variable: JITI_INTEROP_DEFAULT

Jiti combines module exports with the default export using an internal Proxy to improve compatibility with mixed CJS/ESM usage. You can check the current implementation here.

alias

• Type: Object
• Default: -
• Environment variable: JITI_ALIAS

You can also pass an object to the environment variable for inline config. Example: JITI_ALIAS='{"~/*": "./src/*"}' jiti ....

Custom alias map used to resolve IDs.

nativeModules

• Type: Array
• Default: ['typescript']
• Environment variable: JITI_NATIVE_MODULES

List of modules (within node_modules) to always use native require() for them.

transformModules

• Type: Array
• Default: []
• Environment variable: JITI_TRANSFORM_MODULES

List of modules (within node_modules) to transform them regardless of syntax.

importMeta

Parent module's import.meta context to use for ESM resolution. (only used for jiti/native import).

tryNative

• Type: Boolean
• Default: Enabled if bun is detected
• Environment variable: JITI_TRY_NATIVE

Try to use native require and import without jiti transformations first.

jsx

• Type: Boolean | {options}
• Default: false
• Environment Variable: JITI_JSX

Enable JSX support using @babel/plugin-transform-react-jsx.

See test/fixtures/jsx for framework integration examples.

Development

• Clone this repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run pnpm dev
• Run pnpm jiti ./test/path/to/file.ts

License

Published under the MIT license. Made by @pi0 and community 💛