importx

importx

Unified tool for importing TypeScript modules at runtime.

• tsx
• jiti
• bundle-require
• native

Motivation

It's a common need for tools to support importing TypeScript modules at runtime. For example, to support configure files written in TypeScript.

There are so many ways to do that, each with its own trade-offs and limitations. This library aims to provide a simple, unified API for importing TypeScript modules and swap loaders as ease.

By default, it also provides a smart "auto" mode that decides the best loader based on the environment:

• Use native import() for runtimes that support directly importing TypeScript modules (Deno, Bun, or ts-node, tsx CLI).
• Use tsx for modern module environments.
• Use jiti for older Node.js that don't support tsx.
• Use bundle-require when you want to import a module without the ESM cache.

Usage

npm i importx

const mod = await import('importx').then(x => x.import('./path/to/module.ts', import.meta.url))

Loaders

auto

Automatically choose the best loader based on the environment.

graph TD
  A((Auto)) --> IsTS{{"Is importing a TypeScript file?"}}
  IsTS --> |No| Cache{{"Import cache?"}}
  Cache --> |true,null| Native1(["native import()"])
  Cache --> |false| F

  Cache2 --> |false| F
  IsTS --> |Yes| Cache2{{"Import cache?"}}
  Cache2 --> |true,null| D{{"Supports native TypeScript?"}}
  D --> |No| Cache3{{"Import cache?"}}
  D --> |Yes| Native2(["native import()"])
  Cache3 --> |true| Jiti1([jiti])
  Cache3 --> |null| F{{"Is Node.js version range supports tsx?"}}
  F --> |Yes| Tsx3([tsx])
  F --> |No| Jiti2([jiti])

  classDef auto fill:#0f82,stroke:#0f83,stroke-width:2px;
  classDef question fill:#f9f2,stroke:#f9f3,stroke-width:2px;
  classDef cache fill:#eb527120,stroke:#eb527133,stroke-width:2px;
  classDef native fill:#8882,stroke:#8883,stroke-width:2px;
  classDef tsx fill:#09f2,stroke:#09f3,stroke-width:2px;
  classDef jiti fill:#ffde2220,stroke:#ffde2230,stroke-width:2px;
  class A auto;
  class IsTS,D,F question;
  class Cache,Cache2,Cache3 cache;
  class Native1,Native2 native;
  class Tsx1,Tsx2,Tsx3 tsx;
  class Jiti1,Jiti2 jiti;

native

Use the native import() to import the module.

tsx

Use tsx's tsImport API to import the module. Under the hood, it registers Node.js loader API and uses esbuild to transpile TypeScript to JavaScript.

Pros

• Native Node.js loader API, consistent and future-proof.

Limitations

• Requires Node.js ^18.18.0, ^20.6.0 or above.

jiti

Use jiti to import the module. It uses a bundled Babel parser to transpile modules. It runs in CJS mode and has its own cache and module runner.

Pros

• Self-contained, does not dependents on esbuild.
• Own cache and module runner, better and flexible cache control.

Limitations

• Does not support top-level await yet
• Runs in CJS mode (transpiles all TS/ESM to CJS)

bundle-require

Use bundle-require to import the module. It uses esbuild to bundle the entry module, saves it to a temporary file, and then imports it.

Pros

• Get the file list of module dependencies. Helpful for hot-reloading or manifest generation.

Limitations

• It creates a temporary bundle file on importing (will external node_modules).
• Can be inefficient where there are many TypeScript modules in the import tree.
• Always import a new module, does not support module cache.

Cache

By definition, ESM modules are always cached by the runtime, which means you will get the same module instance when importing the same module multiple times. In some scenarios, like a dev server watching for config file changes, the cache may not be desired as you want to get the new module with the latest code on your disk.

importx allows you to specify if you want to have the module cache or not, by providing the cache option:)

const mod = await import('importx')
  .then(x => x.import('./path/to/module.ts', {
    cache: false, // <-- this
    parentURL: import.meta.url,
  }))

Setting cache: null (default) means you don't care about the cache (if you only import the module once).

Note that some loaders always have a cache, and some loaders always have no cache. With the auto loader, we will choose the best loader based on your need. Otherwise, an unsupported combination will throw an error. For example:

// This will throw an error because `bundle-require` does not support cache.
const mod = await import('importx')
  .then(x => x.import('./path/to/module.ts', {
    cache: true,
    loader: 'bundle-require',
    parentURL: import.meta.url,
    // ignoreImportxWarning: true // unless you have this
  }))

Runtime-Loader Compatibility Table

Importing a TypeScript module with importx:

Generated with version v0.0.2 at 2024-05-11T04:17:16.249Z

	native	tsx	jiti	bundle-require
node	Import: ❌ Cache: ❌ No cache: ❌	Import: ✅ Cache: ❌ No cache: ✅	Import: ✅ Cache: ✅ No cache: ✅	Import: ✅ Cache: ❌ No cache: ✅
tsx	Import: ✅ Cache: ✅ No cache: ❌	N/A	N/A	N/A
deno	Import: ✅ Cache: ✅ No cache: ❌	N/A	N/A	N/A
bun	Import: ✅ Cache: ✅ No cache: ❌	N/A	N/A	N/A

Sponsors

License

MIT License © 2023-PRESENT Anthony Fu