npm package: @mause_23/tsblaze
Description: Runtime typescript and ESM support for Node.js (fork with virtualModules support)
Latest version: 2.6.5

# tsblaze

<!-- automd:badges color=F0DB4F bundlephobia -->

[![npm version](https://img.shields.io/npm/v/tsblaze?color=F0DB4F)](https://npmjs.com/package/tsblaze)
[![npm downloads](https://img.shields.io/npm/dm/tsblaze?color=F0DB4F)](https://npmjs.com/package/tsblaze)
[![bundle size](https://img.shields.io/bundlephobia/minzip/tsblaze?color=F0DB4F)](https://bundlephobia.com/package/tsblaze)

<!-- /automd -->

> This is the active development branch. Check out [tsblaze/v1](https://github.com/unjs/tsblaze/tree/v1) for legacy v1 docs and code.

## 🌟 Used in

[Docusaurus](https://docusaurus.io/), [ESLint](https://github.com/eslint/eslint), [FormKit](https://formkit.com/), [Histoire](https://histoire.dev/), [Knip](https://knip.dev/), [Nitro](https://nitro.unjs.io/), [Nuxt](https://nuxt.com/), [PostCSS loader](https://github.com/webpack-contrib/postcss-loader), [Rsbuild](https://rsbuild.dev/), [Size Limit](https://github.com/ai/size-limit), [Slidev](https://sli.dev/), [Tailwindcss](https://tailwindcss.com/), [Tokenami](https://github.com/tokenami/tokenami), [UnoCSS](https://unocss.dev/), [WXT](https://wxt.dev/), [Winglang](https://www.winglang.io/), [Graphql code generator](https://the-guild.dev/graphql/codegen), [Lingui](https://lingui.dev/), [Scaffdog](https://scaff.dog/), [Storybook](https://storybook.js.org), [...UnJS ecosystem](https://unjs.io/), [...60M+ npm monthly downloads](https://npm.chart.dev/tsblaze), [...6M+ public repositories](https://github.com/unjs/tsblaze/network/dependents).

## ✅ 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`](#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](https://github.com/unjs/tsblaze/issues) 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!

```bash
npx tsblaze ./index.ts
```

### Programmatic

Initialize a tsblaze instance:

```js
// 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:

```js
// 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`.

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

CommonJS (sync & deprecated):

```js
// 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:

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

### Register global ESM loader

You can globally register tsblaze using [global hooks](https://nodejs.org/api/module.html#initialize). (Important: Requires Node.js > 20)

```js
import "tsblaze/register";
```

Or:

```bash
node --import tsblaze/register index.ts
```

## 🎈 `tsblaze/native`

You can alias `tsblaze` to `tsblaze/native` to directly depend on runtime's [`import.meta.resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve) and dynamic [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/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](./src/babel.ts) 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](https://github.com/unjs/tsblaze/blob/main/src/utils.ts#L105).

### `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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/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`](https://babeljs.io/docs/babel-plugin-transform-react-jsx).

See [`test/fixtures/jsx`](./test/fixtures/jsx) for framework integration examples.

## Development

- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Run `pnpm dev`
- Run `pnpm tsblaze ./test/path/to/file.ts`

## License

<!-- automd:contributors license=MIT author="pi0" -->

Published under the [MIT](https://github.com/unjs/tsblaze/blob/main/LICENSE) license.
Made by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/tsblaze/graphs/contributors) 💛
<br><br>
<a href="https://github.com/unjs/tsblaze/graphs/contributors">
<img src="https://contrib.rocks/image?repo=unjs/tsblaze" />
</a>

<!-- /automd -->

<!-- automd:with-automd -->