bunchee

> Zero-config bundler for JS/TS packages.

bunchee is a zero configuration bundler makes bundling JS/TS library effortless. It's built on top of Rollup and SWC ⚡️, allowing you to focus on writing code and generating multiple bundles (CommonJS or ESModule) at the same time. It uses the standard exports configuration in package.json as the only source of truth, and uses entry file conventions to match your exports and build them into bundles.

Quick Start

Installation

npm install --save-dev bunchee

If you're using TypeScript

npm install --save-dev bunchee typescript

Configuration

Create your library entry file and package.json.

cd ./my-lib
mkdir src && touch ./src/index.ts

Prepare

# Use bunchee to prepare package.json configuration
npm exec bunchee --prepare
# "If you're using other package manager such as pnpm"
# pnpm bunchee --prepare

# "Or use with npx"
# npx bunchee@latest --prepare

Or you can checkout the following cases to configure your package.json.

{
  "files": ["dist"],
  "exports": {
    "import": "./dist/es/index.mjs",
    "require": "./dist/cjs/index.js"
  },
  "scripts": {
    "build": "bunchee"
  }
}

{
  "files": ["dist"],
  "exports": {
    "import": {
      "types": "./dist/es/index.d.mts",
      "default": "./dist/es/index.mjs"
    },
    "require": {
      "types": "./dist/cjs/index.d.ts",
      "default": "./dist/cjs/index.js"
    }
  },
  "scripts": {
    "build": "bunchee"
  }
}

{
  "files": ["dist"],
  "main": "./dist/cjs/index.js",
  "module": "./dist/es/index.mjs",
  "types": "./dist/cjs/index.d.ts",
  "exports": {
    "import": {
      "types": "./dist/es/index.d.ts",
      "default": "./dist/es/index.js"
    },
    "require": {
      "types": "./dist/cjs/index.d.cts",
      "default": "./dist/cjs/index.cjs"
    }
  },
  "scripts": {
    "build": "bunchee"
  }
}

Build

Then files in src folders will be treated as entry files and match the export names in package.json. For example: src/index.ts will match the exports name "." or the only main export.

Now just run npm run build (or pnpm build / yarn build) if you're using these package managers, bunchee will find the entry files and build them. The output format will based on the exports condition and also the file extension. Given an example:

• It's CommonJS for require and ESM for import based on the exports condition.
• It's CommonJS for .js and ESM for .mjs based on the extension regardless the exports condition. Then for export condition like "node" you could choose the format with your extension.

> [!NOTE] > All the dependencies and peerDependencies will be marked as external automatically and not included in the bundle. If you want to include them in the bundle, you can use the --no-external option.

Usage

File Conventions

While exports field is becoming the standard of exporting in node.js, bunchee also supports to build multiple exports all in one command.

Provide entry files with the name ([name].[ext]) that matches the exported name from exports field in package.json. For instance:

• /src/index.ts will match "." export name or the if there's only one main export.
• /src/lite.ts will match "./lite" export name.

The build script can be just bunchee without configure any input sources for each exports. Of course you can still specify other arguments as you need. Briefly, the entry files from src/ folder will do matching with exports conditions from package.json and build them into bundles.

Assuming you have default export package as "." and subpath export "./lite" with different exports condition listed in package.json

{
  "name": "example",
  "scripts": {
    "build": "bunchee"
  },
  "exports": {
    "./lite": "./dist/lite.js",
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

Then you need to add two entry files index.ts and lite.ts in project root directory to match the export name "." and "./lite", bunchee will associate these entry files with export names then use them as input source and output paths information.

- my-lib/
  |- src/
    |- lite.ts
    |- index.ts
  |- package.json

It will also look up for index. file under the directory having the name of the export path. For example, if you have "./lite": "./dist/lite.js" in exports field, then it will look up for ./lite/index.js as the entry file as well.

Multiple Runtime

For exports condition like react-native, react-server and edge-light as they're special platforms, they could have different exports or different code conditions. In this case bunchee provides an override input source file convention if you want to build them as different code bundle.

For instance:

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

Executables

To build executable files with the bin field in package.json, bunchee requires you to create the bin directory under src directory. The source file matching will be same as the entry files convention.

For example:

|- src/
  |- bin/
    |- index.ts

This will match the bin field in package.json as:

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

For multiple executable files, you can create multiple files under the bin directory.

|- src/
  |- bin/
    |- foo.ts
    |- bar.ts

This will match the bin field in package.json as:

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

> Note: For multiple bin files, the filename should match the key name in the bin field.

Server Components

bunchee supports to build server components and server actions with library directives like "use client" or "use server". It will generate the corresponding chunks for client and server that scope the client and server boundaries properly. Then when the library is integrated to an app such as Next.js, app bundler can transform the client components and server actions correctly and maximum the benefits.

If you're using "use client" or "use server" in entry file, then it will be preserved on top and the dist file of that entry will become a client component. If you're using "use client" or "use server" in a file that used as a dependency for an entry, then that file containing directives be split into a separate chunk and hoist the directives to the top of the chunk.

Shared Modules (Experimental)

There're always cases that you need to share code among bundles but they don't have to be a separate entry or exports. You want to have them bundled into a shared chunk and then use them in different bundles. You can use shared module convention [name].[layer]-runtime.[ext] to create shared modules bundles.

// src/util.shared-runtime.js
export function sharedUtil() {
  /* ... */
}

// src/index.js
import { sharedUtil } from './util.shared-runtime'

// src/lite.js
import { sharedUtil } from './util.shared-runtime'

With multiple runtime bundles, such as having default and react-server together. They could have the modules that need to be shared and kept as only one instance among different runtime bundles. You can use the shared module convention to create shared modules bundles for different runtime bundles.

'use client'
// src/app-context.shared-runtime.js
export const AppContext = React.createContext(null)

// src/index.js
import { AppContext } from './app-context.shared-runtime'

// src/index.react-server.js
import { AppContext } from './app-context.shared-runtime'

CLI

CLI Options

bunchee CLI provides few options to create different bundles or generating types.

• Output (-o ): Specify output filename.
• Format (-f ): Set output format (default: 'esm').
• External (--external ): Specifying extra external dependencies, by default it is the list of dependencies and peerDependencies from package.json. Values are separate by comma.
• Target (--target ): Set ECMAScript target (default: 'es2015').
• Runtime (--runtime ): Set build runtime (default: 'browser').
• Environment (--env ): Define environment variables. (default: NODE_ENV, separate by comma)
• Working Directory (--cwd ): Set current working directory where containing package.json.
• Minify (-m): Compress output.
• Watch (-w): Watch for source file changes.
• No Clean(--no-clean): Do not clean the dist folder before building. (default: false)
• TSConfig (`--tsconfig