bunchee

Bunchee detects the output format based on the package.json field or the file extension.

Mapping package.json fields to formats

• main or exports: Default format
• types or exports.types: TypeScript declaration
• exports.require: CommonJS
• exports.import: Default
• bin: Default

Default format by extension

• .js: Determined by package.json#type (CommonJS by default)
• .cjs: Always CommonJS
• .mjs: Always ECMAScript Modules

bunchee 7 uses a shared module graph to build entries. This approach:

• Avoids rebuilding common modules.
• Improves declaration performance.
• Keeps directive layers (such as use client, use server, and use cache) separate.

Note for consumers: If your package inspects generated chunk names, treat these names as build artifacts. You should update any snapshots after migrating to bunchee 7.

To share a chunk across multiple bundles (e.g., a single instance of React context or shared utils) without making them public entry points, prefix the file or directory with an underscore (_).

Files like src/_util.js or src/_components/** are treated as shared modules. Bunchee will bundle them into a separate private chunk that is referenced by multiple entry bundles, ensuring they remain a single instance across different runtime bundles.

// src/_util.js
export function sharedUtil() { ... }

// src/index.js
import { sharedUtil } from './_util'

Bunchee is a zero-config bundler that uses your package.json exports field as the single source of truth for entry points.

To get started:

1. Install bunchee and typescript.
2. Define your package metadata and entry points in package.json.
3. Run the bunchee command via your build script.

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

Bunchee provides built-in support for importing non-JS assets:

CSS

Importing .css files will bundle the CSS into the JS bundle and automatically insert a <style> tag into the document head at runtime.

Text and Data Files

• Files with .txt or .data extensions are bundled as string content.
• You can use the ?raw query parameter to import any file type as raw text content.

// Bundles as string content
import data from './data.txt'

// Raw import for any file type
import readme from './README.md?raw'
import config from './config.json?raw'

Bunchee uses files in your src directory as entry points. It automatically matches these files to the exports field in your package.json.

For example, src/index.ts matches the . export, src/lite.ts matches ./lite, and src/react/index.ts matches ./react.

Wildcard Exports

You can use wildcard patterns in the exports field to automatically generate exports for multiple files. The * is substituted in both the export path and the output path.

{
  "exports": {
    ".": "./dist/index.js",
    "./features/*": "./dist/features/*.js"
  }
}

To build executable files defined in the bin field of package.json, create a bin directory under src/. The source file matching follows the same convention as entry files.

For multiple binaries, the filename under src/bin/ must match the key name in the bin field.

// package.json
{
  "bin": {
    "foo": "./dist/bin/a.js",
    "bar": "./dist/bin/b.js"
  }
}

Directory structure:

|- src/
  |- bin/
    |- a.ts
    |- b.ts

By default, dependencies and peerDependencies are marked as external and will not be included in the bundle.

• To include them in the bundle, use the --no-external CLI option.
• Alternatively, you can import devDependencies in your source code to have them bundled.
• You can also manually specify extra external dependencies using --external=dep1,dep2.

Bunchee supports path aliasing via TypeScript paths configuration or the Node.js imports field in package.json. It will resolve these aliases to the correct file paths during bundling.

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

The bunchee package is now an ESM-only package. If you are consuming the bunchee Node.js API, you must replace CommonJS require statements with ESM import statements.

-const { bundle } = require('bunchee')
+import { bundle } from 'bunchee'