# bunchee
bunchee is a zero-config TypeScript & JavaScript bundler designed to create optimized Node.js and browser-friendly packages. It focuses on simplicity, speed, and developer-friendly defaults, making it an excellent choice for bundling modern JavaScript libraries.

## Latest Release: bunchee 7.0.0

- Up to 5.3x faster than bunchee 6.12.2 on a 57-entry build with declaration output (median of seven warm runs on Node.js 24.18).
- New package lint checks detect invalid export-condition ordering, missing declared outputs, and unsafe `workspace:` dependency ranges before publishing.
- Package preparation is ESM-first and uses standards-based package exports.

Release notes: https://github.com/huozhi/bunchee/releases/tag/v7.0.0

### Migrating from bunchee 6

- bunchee 7 requires Node.js 22.12 or newer.
- The default JavaScript target is ES2022. Pass `--target` or configure `compilerOptions.target` when an older output target is required.
- The `bunchee` package itself is ESM. Replace CommonJS `require('bunchee')` calls with ESM imports.
- `bunchee prepare` generates ESM-only packages by default. Pass `--cjs` to generate both ESM and CommonJS exports.
- The old `--prepare` build flag has been removed. Run `bunchee prepare` explicitly.
- TypeScript 7 projects must install `@typescript/typescript6` for declaration generation.

Complete migration guide: https://github.com/huozhi/bunchee/blob/main/docs/MIGRATION.md

## Key Features
- **Zero Configuration**: Bundles projects with sensible defaults out of the box.
- **Tree Shaking**: Removes unused code to produce smaller bundles.
- **TypeScript Support**: Handles `.ts` and `.tsx` files seamlessly.
- **ESM and CJS Outputs**: Supports ESM-only, CJS-only, and dual-module packages.
- **Source Maps**: Supports source map generation for easier debugging.
- **CSS/JSON Asset Bundling**: Automatically processes non-JavaScript assets for compatibility.
- **Raw File Imports**: Import any file as string content using `.txt`/`.data` extensions or `?raw` query parameter.
- **Server Components**: Supports React Server Components and Server Actions with `"use client"` and `"use server"` directives, automatically splitting code into separate chunks.
- **Node Binary Support**: Builds executable CLI tools from `bin` field in package.json with automatic source file matching.
- **Wildcard Exports**: Supports wildcard patterns in package.json exports field for dynamic subpath exports.
- **Fast Build Times**: Built with optimized tooling for rapid iteration.

## Installation
Install bunchee as a development dependency in your project:
```bash
npm install --save-dev bunchee typescript
```

bunchee 7 requires Node.js 22.12 or newer and targets ES2022 by default.

TypeScript 7 users must also install the official compatibility API package:

```bash
npm install --save-dev @typescript/typescript6
```

Migrating from bunchee 6? See the [bunchee 7 migration guide](https://github.com/huozhi/bunchee/blob/main/docs/MIGRATION.md).

## Usage
### Build
Build a project:
```sh
mkdir src && touch ./src/index.ts && touch package.json
```

Add the package metadata in `package.json`.
```json
{
  "name": "coffee",
  "type": "module",
  "main": "./dist/index.js",
  "scripts": {
    "build": "bunchee"
  }
}
```

Run build:
```sh
npm run build
```

### CLI
Bundle a JavaScript or TypeScript entry file:
```bash
bunchee src/index.js --output dist/bundle.js
```

### API
Use bunchee programmatically in your Node.js scripts:
```javascript
import path from 'node:path'
import { bundle } from 'bunchee'

await bundle(path.resolve('src/index.js'), {
  file: path.resolve('dist/bundle.js'),
})
```

## Example Configuration
Although bunchee requires no config, you can customize options via CLI flags or programmatically:
- Specify input and output files
- Enable/disable source maps
- Choose output formats (ESM, CJS)

## Asset Handling
### Text Files
Import files as string content using `.txt` or `.data` extensions:
```javascript
import data from './content.txt'  // Imports as string
```

### Raw Imports
Import any file as raw text using the `?raw` query parameter:
```javascript
import readme from './README.md?raw'    // Markdown as string
import config from './config.json?raw'  // JSON as string (not parsed)
import styles from './styles.css?raw'   // CSS as string
```

## Server Components

bunchee supports building React Server Components and Server Actions with directives like `"use client"` or `"use server"`. It automatically generates separate chunks for server or client boundaries, preserving the directives properly. When integrated with frameworks like Next.js, it correctly handles the boundaries with split chunks.

Example:
```javascript
// src/client.tsx
'use client'
export function ClientComponent() {
  return <div>Client Component</div>
}

// src/action.ts
'use server'
export async function serverAction() {
  // Server action code
}
```

bunchee will bundle these into separate chunks, maintaining the `"use client"` and `"use server"` directives in the output.

## Node Binary Support

bunchee supports building executable CLI tools using the `bin` field in package.json. Create a `bin` directory under `src` directory, and bunchee will automatically match the source files to the binary entries.

### Single Binary
```bash
src/
  bin/
    index.ts
```

```json
{
  "bin": "./dist/bin.js"
}
```

### Multiple Binaries
For multiple executable files, create multiple files under the `bin` directory. The filename should match the key name in the `bin` field:

```bash
src/
  bin/
    foo.ts
    bar.ts
```

```json
{
  "bin": {
    "foo": "./dist/bin/foo.js",
    "bar": "./dist/bin/bar.js"
  }
}
```

The source file matching follows the same convention as entry files, making it easy to build CLI tools alongside your library.

## Wildcard Exports

bunchee supports wildcard patterns in the package.json `exports` field, allowing you to dynamically export subpaths based on your source file structure.

Example:
```json
{
  "exports": {
    "./features/*": "./dist/features/*.js"
  }
}
```

With source files like:
```
src/
  features/
    auth.ts
    user.ts
    settings.ts
```

bunchee will automatically expand the wildcard pattern to:
```json
{
  "exports": {
    "./features/auth": "./dist/features/auth.js",
    "./features/user": "./dist/features/user.js",
    "./features/settings": "./dist/features/settings.js"
  }
}
```

The wildcard pattern matches files in the `src` directory and automatically creates corresponding exports. This is useful for libraries that want to expose multiple subpath exports without manually maintaining the exports map.

## Contributions
Contributions are welcome! Check out the repository's [issues](https://github.com/huozhi/bunchee/issues) for more information.

## License
bunchee is open-source and available under the [MIT License](https://github.com/huozhi/bunchee/blob/main/LICENSE).