Mini-TSDown: Minimal TypeScript Bundler

0.1.9 · active · verified Wed Apr 22

mini-tsdown is a minimal TypeScript library bundler, currently at version 0.1.9, designed primarily for learning purposes and providing a performant build experience. It leverages the Rust-based bundler Rolldown and the Rust-based parser/linter Oxc, offering fast bundling for TypeScript projects. The tool supports multi-format output (ESM and CJS), automatically generates TypeScript declaration files (.d.ts), includes a watch mode for development, and features a flexible hook system for customizing the build lifecycle. Configuration can be managed via dedicated config files (TS, JS, JSON) or CLI options. While its release cadence is not formally defined due to its early stage and "learning purposes" designation, it provides a lightweight, performant alternative focused on TypeScript library bundling, differentiating itself from larger, more general-purpose bundlers by its minimal approach and Rust-powered core.

Common errors

```
Error: Cannot find module 'typescript'
```
cause The `typescript` peer dependency is missing from your project's `devDependencies`.

fix Install TypeScript as a development dependency: `pnpm add -D typescript` or `npm install --save-dev typescript`.
```
Error: Entry point 'src/index.ts' not found.
```
cause The specified entry file either does not exist or the path provided is incorrect.

fix Verify the `entry` path in your `mini-tsdown.config.ts` or the CLI command `npx mini-tsdown <entry-file>` points to an existing file in your project structure.
```
TypeError: defineConfig is not a function
```
cause Attempting to use `defineConfig` with CommonJS `require()` syntax in a TypeScript configuration file, which expects ESM `import`.

fix Ensure your `mini-tsdown.config.ts` uses ESM `import { defineConfig } from 'mini-tsdown'` and that your environment (tsconfig `module` and `moduleResolution` settings) is configured for TypeScript with ESM.

Warnings

breaking As `mini-tsdown` is an early-stage project (v0.1.9) created 'for learning purposes', its API is subject to frequent and potentially breaking changes without strict adherence to semantic versioning. Configuration options, CLI flags, and programmatic interfaces may change significantly between minor versions.
Fix: Review the latest README and changelog (if available) for each update. Pin exact versions in `package.json` to avoid unexpected breakage in production environments.
gotcha `mini-tsdown` requires a peer dependency on `typescript` (v5.0.0 or v6.0.0). Failing to install a compatible version will prevent type declaration generation and potentially other TypeScript-related features from working correctly, leading to build failures.
Fix: Ensure `typescript@^5.0.0` or `typescript@^6.0.0` is installed as a `devDependency` in your project: `pnpm add -D typescript` or `npm install --save-dev typescript`.
gotcha CLI options take precedence over options defined in `mini-tsdown.config.ts`. If both are provided for the same setting (e.g., `--format esm` via CLI and `format: ['cjs']` in config), the CLI value will always override the configuration file setting.
Fix: Understand the option precedence: CLI flags override configuration file settings. Use the config file for default build settings and CLI for temporary overrides or specific, one-off build commands.

Install

npm install mini-tsdown npm
yarn add mini-tsdown yarn
pnpm add mini-tsdown pnpm

Imports

defineConfig
wrong:
```
const defineConfig = require('mini-tsdown').defineConfig
```
correct:
```
import { defineConfig } from 'mini-tsdown'
```
Primarily used in `mini-tsdown.config.ts` for type-safe configuration. Always use ESM `import`.

build

wrong:

const build = require('mini-tsdown').build

correct:

import { build } from 'mini-tsdown'

The core programmatic API function. Returns a Promise.

BuildOptions
```
import type { BuildOptions } from 'mini-tsdown'
```
Used for type annotations when defining build configurations programmatically or for inline options.

Quickstart

Shows how to programmatically bundle a TypeScript project, generating ESM and CJS outputs with type declarations and sourcemaps.

import { build } from 'mini-tsdown';

async function bundleLibrary() {
  try {
    await build({
      entry: 'src/index.ts', // Adjust to your main entry point
      format: ['esm', 'cjs'],
      outDir: 'dist',
      dts: true,
      sourcemap: true,
      external: ['some-peer-dep'], // Example: mark a package as external
    });
    console.log('Build complete successfully!');
  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

bundleLibrary();

view raw JSON →