bun-plugin-isolated-decl

bun-plugin-isolated-decl

A Bun plugin for generating isolated declaration files (.d.ts) from TypeScript sources using the oxc-transformer. This is the Bun-specific version of unplugin-isolated-decl.

Features

• ⚡ Ultra-Fast: Generates .d.ts files significantly faster than tsc
• 🔧 Powered by oxc: Utilises the efficient oxc-transformer for blazing-fast performance
• 🔌 Bun Integration: Seamlessly integrates with Bun's build process
• 🚀 Zero Config: Works out of the box with no configuration required
• 🎯 Focused Functionality: Optimised for TypeScript 5.5's isolatedDeclarations option
• 🔄 Ecosystem Compatibility: Bun version of unplugin-isolated-decl

Installation

Install the plugin and its peer dependencies:

bun add -d bun-plugin-isolated-decl typescript oxc-transform

Usage

import isolatedDecl from 'bun-plugin-isolated-decl';
await Bun.build({
	entrypoints: ['./index.ts'],
	outdir: './dist',
	plugins: [isolatedDecl()],
	// ... other configuration options
});

You can also check the example script: tests.

Options

You can pass options to the plugin:

isolatedDecl({
	forceGenerate: true // Generate declaration files even if there are errors
});

Option	Type	Default	Description
forceGenerate	boolean	false	If true, generates declaration files even when there are errors in the source

How it works

• The plugin processes all entrypoints specified in your Bun build configuration.
• For each entrypoint, it uses the oxc-transformer to generate isolated declaration files.
• If errors are encountered and forceGenerate is false, it will log the errors and skip generation for that file.
• Generated declaration files are written to the specified outdir with a .d.ts extension.

Comparison with bun-plugin-dts

While both plugins aim to generate declaration files, they have some key differences:

• Speed: bun-plugin-isolated-decl is significantly faster than bun-plugin-dts due to its use of oxc-transformer instead of tsc.

• Compatibility:

  • bun-plugin-dts uses tsc and can generate types for all TypeScript code.
  • bun-plugin-isolated-decl is optimised for and limited to source code that is compatible with TypeScript 5.5's isolatedDeclarations option.

• Use Case:

  • Choose bun-plugin-dts if you need comprehensive type generation for all TypeScript features.
  • Choose bun-plugin-isolated-decl if you prioritise speed and your codebase is compatible with isolated declarations.

Limitations and Advantages

• Limitation: This plugin can only handle source code that is compatible with TypeScript 5.5's isolatedDeclarations option. It may not work for all TypeScript projects, especially those using advanced type features.

• Advantage: For compatible codebases, this plugin offers extremely fast declaration file generation, significantly outperforming traditional tsc-based solutions.

Relationship to unplugin-isolated-decl

bun-plugin-isolated-decl is the Bun-specific implementation of unplugin-isolated-decl .

Licence

ISC Licence

Author

ryoppippi

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you find a bug or have a suggestion, please file an issue on the GitHub repository.