# bunchee: zero-config bundling for npm packages

> bunchee is a TypeScript-based bundler for JavaScript, TypeScript and JSX libraries. It derives entry points and output formats from package.json, with support for CommonJS, ECMAScript Modules and TypeScript declarations.

**huozhi/bunchee** — Zero config bundler for npm packages

- Repository: https://github.com/huozhi/bunchee
- Website: https://bunchee-it.vercel.app
- Stars: 1,403 · Forks: 39
- Language: TypeScript
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/huozhi-bunchee

## Why bunchee targets npm library packaging

bunchee addresses the gap between an ordinary source tree and the package structure required for publication. It is aimed at authors of JavaScript, TypeScript and JSX libraries who need separate package entry points, module formats and type declarations without maintaining a large bundler configuration.

The project uses the exports field in package.json as its central source of truth. Source files under src correspond to published export names. According to the README, src/index.ts represents the default export, src/lite.ts represents ./lite and src/react/index.ts represents ./react. This convention makes the build configuration largely part of the package manifest.

That approach is useful for small and medium libraries, but it imposes a specific layout. Projects with arbitrary filenames or a custom discovery scheme may need to reorganize source files around bunchee's conventions. The zero-config label describes limited setup, not unrestricted project structure.

## How package.json determines bunchee entries

bunchee resolves entry files by matching each export name to the corresponding path under src. A package can expose a default entry and several subpaths. The README also documents wildcard exports, where `./features/*` maps to files under `src/features/`. bunchee substitutes the wildcard segment in both the export name and output filename, generating entries such as `./features/foo` and `./features/bar` for discovered source files.

Package metadata also controls output format. The recognized fields include main, types, exports, exports.require, exports.import, exports.types, bin and bin.<name>. A require condition produces CommonJS, while an import condition uses the default format. A types field or types condition requests TypeScript declaration output.

For JavaScript outputs, bunchee considers file extensions and package type. A `.cjs` target is always CommonJS, an `.mjs` target is an ECMAScript Module, and `.js` follows the nearest package type, using CommonJS by default when the package is not marked as a module. This gives authors several ways to express dual-package output, but it also makes incorrect package metadata a direct cause of incorrect resolution.

## Installing bunchee and running a first build

The README's installation command adds bunchee and TypeScript as development dependencies. The TypeScript dependency is relevant because bunchee generates declaration files from package metadata.

```bash
npm install --save-dev bunchee typescript
```

The README warns about TypeScript 7 and newer. It states that the `typescript` package no longer contains the JavaScript compiler API used for declaration generation, and instructs TypeScript 7 users to install `@typescript/typescript6`. bunchee will detect that compatibility package automatically.

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

A first package can define a local build script in package.json. The documented quick-start configuration uses the name `coffee`, marks the package as an ESM package and points main at the generated file.

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

After creating `src/index.ts`, run the package script. The README states that bunchee should generate output according to the configured fields and exports.

```bash
npm run build
```

The quick-start configuration is deliberately limited. The README does not show the complete generated directory listing, so the expected result beyond the configured output path is not stated.

## Dual CommonJS and ESM package output

bunchee can represent CommonJS and ECMAScript Module output within the same package by assigning each condition its own target. In the README's entry example, the default export points `./dist/index.js` to its import condition and `./dist/index.cjs` to its require condition.

```json
{
  "name": "coffee",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./lite": "./dist/lite.js",
    "./react": "./dist/react.js"
  }
}
```

This arrangement asks Node.js and other package resolvers to select the file associated with the requested condition. The source-side mapping remains conventional: the default export comes from `src/index.ts`, `./lite` comes from `src/lite.ts` and `./react` comes from `src/react/index.ts`.

Dual output has a cost. Every target must be declared correctly, and source changes must remain valid for both module systems. The README does not describe automated compatibility checks for imported dependencies in each output, so package authors still need to review the emitted JavaScript when CommonJS support is important.

## Runtime conditions for React and edge targets

bunchee recognizes special platform conditions such as `react-native`, `react-server` and `edge-light`. The README says these conditions may require different export files or code paths. It provides an override input source convention when a package needs separate bundles for those environments.

```json
{
  "exports": {
    "react-server": "./dist/react-server.mjs",
    "edge-light": "./dist/edge-light.mjs",
    "import": "./dist/index.mjs"
  }
}
```

The output metadata alone does not describe the complete override source naming rule in the README excerpt. Before adopting bunchee for a React Server Components package, an author should compare this convention with the example under `examples/server-actions` and confirm that every condition maps to a real source file.

This is one area where package.json still carries significant design responsibility. bunchee can use specialized conditions, but the README does not claim that any React or edge application can be bundled without source-specific decisions.

## External packages, included code and aliases

bunchee externalizes packages listed in dependencies and peerDependencies. Those packages remain consumer-installed dependencies and are not copied into the generated bundle. Imports from devDependencies may instead be included. 

This dependency boundary is clear, but it can expose packaging mistakes. A library that imports a package at runtime while listing it only under devDependencies may publish a bundle that works locally but fails after installation. Conversely, externalizing a dependency means the resulting package relies on consumers resolving the declared version range.

bunchee also resolves TypeScript paths and Node.js package imports. A private name can point directly at a source module through the package.json imports field.

```json
{
 "imports": {
 "#util": "./src/utils.ts"
 }
}
```

The README states that bunchee resolves this alias to the source file. It does not document conflict behavior when the same name also appears in TypeScript paths, nor does it describe alias rewriting in emitted output.

## CLI entries, repository maintenance and adoption limits

bunchee also builds executable files declared through package.json's bin field. The documented source convention places executables in `src/bin`. A file named `src/bin/index.ts` can correspond to a single output such as `./dist/bin.js`.

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

The README ends while discussing multiple binaries, so it does not fully document their naming rules. bunchee's own package metadata also requires Node.js `>=22.12.0`. Teams supporting older runtimes must check that engine constraint before adding the dependency.

Maintenance status comes from the repository record. The repository is not archived, its last push was on 2026-10-14 and release v7.0.2 was published on 2026-10-14. Version 7.0.0 was released on 2026-07-31, so adopters arriving from version 6 should consult the linked bunchee 7 migration guide. Upgrade work includes checking renamed output behavior, export mappings and TypeScript declaration compatibility. The repository metadata does not identify a license, so it does not support a conclusion about redistribution rights.

bunchee is a poor fit when custom Rollup plugins, manual chunking or application bundling dominate the build. It is better suited to publishable libraries whose src layout and package metadata already match its conventions.

## Conclusion

bunchee fits package authors who want package.json to control entry points, module formats and dependency boundaries. It is less suitable for applications that require custom Rollup behavior or unusual entry conventions. Check the exports map, Node.js requirement, TypeScript compiler API compatibility and generated package files before adopting bunchee 7.0.2.

## FAQ

### How do I install bunchee for a TypeScript npm package?

Run `npm install --save-dev bunchee typescript`. For TypeScript 7 or newer, the README also requires `@typescript/typescript6` for declaration generation.

### How does bunchee map package exports to source files?

bunchee matches exports with files under `src`. The default export uses `src/index.ts`, while subpaths can map to files such as `src/lite.ts` or directories such as `src/react/index.ts`.

### Does bunchee bundle dependencies listed in package.json?

Packages in dependencies and peerDependencies remain external. Imports from devDependencies may be bundled, and `bunchee --no-external` disables normal externalization.

### Which module formats does bunchee generate?

bunchee supports CommonJS and ECMAScript Modules. Conditions, file extensions and the package type field determine each output format, with `.cjs` selecting CommonJS and `.mjs` selecting ESM.

### What Node.js version does bunchee require?

The repository's package metadata specifies Node.js `>=22.12.0` in the engines.node field.

## Sources

- [huozhi/bunchee on GitHub](https://github.com/huozhi/bunchee)
- [Issues](https://github.com/huozhi/bunchee/issues)
- [Project website](https://bunchee-it.vercel.app)
- [README](https://github.com/huozhi/bunchee/blob/main/README.md)
- [Releases](https://github.com/huozhi/bunchee/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/huozhi-bunchee