tsblaze

This is the active development branch. Check out tsblaze/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 compatibility, tsblaze >=2.1 enabled interopDefault using a new Proxy method. If you migrated to 2.0.0 earlier, 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 tsblaze CLI to quickly run any script with TypeScript and native ESM support!

npx tsblaze ./index.ts

Programmatic

Initialize a tsblaze instance:

// ESM
import { createtsblaze } from "tsblaze";
const tsblaze = createtsblaze(import.meta.url);

// CommonJS (deprecated)
const { createtsblaze } = require("tsblaze");
const tsblaze = createtsblaze(__filename);

Import (async) and resolve with ESM compatibility:

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

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

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

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

CommonJS (sync & deprecated):

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

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

You can also pass options as the second argument:

const tsblaze = createtsblaze(import.meta.url, { debug: true });

Register global ESM loader

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

import "tsblaze/register";

Or:

node --import tsblaze/register index.ts

🎈 tsblaze/native

You can alias tsblaze to tsblaze/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 tsblaze.

⚙️ Options

debug

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

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

fsCache

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

Filesystem source cache (enabled by default)

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

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

rebuildFsCache

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

Rebuild filesystem source cache created by fsCache.

moduleCache

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

Runtime module cache (enabled by default).

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

When enabled, tsblaze 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: tsblaze_SOURCE_MAPS

Add inline source map to transformed source for better debugging.

interopDefault

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

tsblaze 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: tsblaze_ALIAS

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

Custom alias map used to resolve IDs.

nativeModules

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

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

transformModules

• Type: Array
• Default: []
• Environment variable: tsblaze_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 tsblaze/native import).

tryNative

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

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

jsx

• Type: Boolean | {options}
• Default: false
• Environment Variable: tsblaze_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 tsblaze ./test/path/to/file.ts

License

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