unjs
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.cacheintegration - Filesystem transpile with hard disk caches
- ESM Loader support
- JSX support (opt-in)
[!IMPORTANT] To enhance compatibility, jiti
>=2.1enabledinteropdefaultusing a new Proxy method. If you migrated to2.0.0earlier, this might have caused behavior changes. In case of any issues during the upgrade, please report so we can investigate to solve them. 🙏🏼
💡 Usage
CLI
You can use jiti CLI to quickly run any script with TypeScript and native ESM support!
npx jiti ./index.tsProgrammatic
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 💛