unplugin-isolated-decl/README.md

A blazing-fast tool for generating isolated declarations.

# unplugin-isolated-decl

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![JSR][jsr-src]][jsr-href]
[![Unit Test][unit-test-src]][unit-test-href]

⚡️ A blazing-fast tool for generating isolated declarations.

## Features

- 🚀 **Fast**: Generates `.d.ts` files significantly faster than `tsc`.
- 🎨 **Transformer**: Support Oxc, SWC, and TypeScript transformer.
- 📦 **Zero Config**: No configuration required, works out of the box.
- ✨ **Bundler Support**: Works with Vite, Rollup, esbuild and Farm.

> [!TIP]
> For Rolldown users, you can use the [`rolldown-plugin-dts`](https://github.com/sxzz/rolldown-plugin-dts) for a more powerful and flexible solution.

## Installation

```bash
# npm
npm i -D unplugin-isolated-decl

# jsr
npx jsr add -D @unplugin/isolated-decl
```

## Usage

<details>
<summary>Vite</summary><br>

```ts
// vite.config.ts
import UnpluginIsolatedDecl from 'unplugin-isolated-decl/vite'

export default defineConfig({
  plugins: [UnpluginIsolatedDecl()],
})
```

<br></details>

<details>
<summary>Rollup</summary><br>

```ts
// rollup.config.js
import UnpluginIsolatedDecl from 'unplugin-isolated-decl/rollup'

export default {
  plugins: [UnpluginIsolatedDecl()],
}
```

<br></details>

<details>
<summary>Rolldown</summary><br>

```ts
// rolldown.config.js
import UnpluginIsolatedDecl from 'unplugin-isolated-decl/rolldown'

export default {
  plugins: [UnpluginIsolatedDecl()],
}
```

<br></details>

<details>
<summary>esbuild</summary><br>

```ts
// esbuild.config.js
import { build } from 'esbuild'

build({
  plugins: [require('unplugin-isolated-decl/esbuild')()],
})
```

<br></details>

<details>
<summary>Farm</summary><br>

```ts
// farm.config.ts
import UnpluginIsolatedDecl from 'unplugin-isolated-decl/farm'

export default defineConfig({
  plugins: [UnpluginIsolatedDecl()],
})
```

<br></details>

## Options

```ts
export interface Options {
  include?: FilterPattern
  exclude?: FilterPattern
  enforce?: 'pre' | 'post' | undefined
  /**
   * You should install the transformer manually if you are not using oxc.
   * swc: @swc/core
   * typescript: typescript
   *
   * @default oxc
   */
  transformer?: 'oxc' | 'swc' | 'typescript'
  /**
   * Whether to generate declaration source maps.
   *
   * Supported by `typescript` and `oxc` transformer only.
   *
   * @link https://www.typescriptlang.org/tsconfig/#declarationMap
   */
  sourceMap?: boolean

  transformOptions?: TranspileOptions
  ignoreErrors?: boolean
  /** An extra directory layer for output files. */
  extraOutdir?: string

  rewriteImports?: (
    id: string,
    importer: string,
  ) => string | void | null | undefined
}
```

### `rewriteImports`

Rewrite imports in `.d.ts` files. (esbuild support is not available)

Here is an example of rewriting imports on Rollup:

```js
// rollup.config.js
import alias from '@rollup/plugin-alias'

export default {
  // ...
  plugins: [
    alias({ entries: [{ find: '~', replacement: '.' }] }),
    UnpluginIsolatedDecl({
      rewriteImports(id, importer) {
        if (id[0] === '~') return `.${id.slice(1)}`
      },
    }),
    // ...
  ],
}
```

### `patchCjsDefaultExport`

Patch `export default` in `.d.cts` to `export =`

---

> [!NOTE]
> For the exhaustive set of options check [options](src/core/options.ts)

## Sponsors

<p align="center">
  <a href="https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg">
    <img src='https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg'/>
  </a>
</p>

## License

[MIT](./LICENSE) License © 2024-PRESENT [Kevin Deng](https://github.com/sxzz)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/unplugin-isolated-decl.svg
[npm-version-href]: https://npmjs.com/package/unplugin-isolated-decl
[npm-downloads-src]: https://img.shields.io/npm/dm/unplugin-isolated-decl
[npm-downloads-href]: https://www.npmcharts.com/compare/unplugin-isolated-decl?interval=30
[jsr-src]: https://jsr.io/badges/@unplugin/isolated-decl
[jsr-href]: https://jsr.io/@unplugin/isolated-decl
[unit-test-src]: https://github.com/unplugin/unplugin-isolated-decl/actions/workflows/unit-test.yml/badge.svg
[unit-test-href]: https://github.com/unplugin/unplugin-isolated-decl/actions/workflows/unit-test.yml