Bundlib

Common errors

• Error: Cannot find module 'bundlib' or its corresponding type declarations.

  cause Attempting to `require()` Bundlib in a CommonJS context when it's primarily an ESM package, or incorrect module resolution in a TypeScript project.
  fix Ensure you are using ESM `import` statements (e.g., `import { defineConfig } from 'bundlib';`). For TypeScript, verify `moduleResolution` in `tsconfig.json` supports modern ESM (e.g., `"node16"` or `"bundler"`).

• Error: Your current Node.js version is X. Bundlib requires Node.js >=18.

  cause Running Bundlib with an unsupported Node.js version as specified in its `engines` field.
  fix Update your Node.js environment to version 18 or newer. Use `nvm install 18` and `nvm use 18` or similar version management tools.

• Error: Missing "input" option

  cause The Rollup configuration generated by Bundlib lacks a specified entry point for bundling.
  fix Ensure your `bundlib.config.ts` or `package.json` configuration explicitly defines the `input` option, pointing to your library's main source file (e.g., `input: 'src/index.ts'`).

• TypeError: bundlib.defineConfig is not a function

  cause Incorrect import of `defineConfig` or attempting to access it as a property of a default import.
  fix Use named import: `import { defineConfig } from 'bundlib';`. If using CommonJS, ensure your setup correctly transpiles ESM or update to an ESM-compatible environment.

Warnings

• gotcha Bundlib is explicitly stated to be "under development". This implies that APIs might still evolve, and users should be prepared for potential changes or edge cases as the project matures.
  Fix: Monitor official releases and changelogs closely for updates. Consider pinning to minor versions and thoroughly testing updates in a staging environment.
• breaking Bundlib requires Node.js version >=18. Running with older Node.js versions will result in execution errors.
  Fix: Upgrade your Node.js environment to version 18 or newer using tools like `nvm` or by installing a recent Node.js distribution.
• breaking CLI commands for `build` and `watch` were significantly refactored and introduced in version 0.21.5, potentially changing how users interact with the bundler from the command line.
  Fix: Refer to the updated documentation or run `bundlib --help` to understand the correct CLI syntax for `build` and `watch` commands. Ensure your `package.json` scripts are updated accordingly.
• gotcha Upgrades to underlying Rollup plugins (e.g., `@rollup/plugin-commonjs` fix in v0.21.4) can introduce subtle breaking changes or require configuration adjustments, particularly for browser builds.
  Fix: Always test new Bundlib versions thoroughly, especially if you rely on specific Rollup plugins or complex build configurations. Consult the Rollup plugin's changelogs for breaking changes when updating Bundlib.

Install

• npm install bundlib npm
• yarn add bundlib yarn
• pnpm add bundlib pnpm

Imports

• defineConfig
  wrong:

  const { defineConfig } = require('bundlib');

  correct:

  import { defineConfig } from 'bundlib'

  Primarily used in `bundlib.config.ts` or `bundlib.config.js` files for type-safe configuration. CommonJS `require` is incorrect in most modern Node.js environments as Bundlib targets ESM.
• bundlib
  wrong:

  const bundlib = require('bundlib').bundlib;

  correct:

  import { bundlib } from 'bundlib'

  The main programmatic function for initiating a build. Bundlib is an ESM-first package, requiring named imports even for the main function.
• BundlibConfig
  wrong:

  import { BundlibConfig } from 'bundlib'

  correct:

  import type { BundlibConfig } from 'bundlib'

  This is a TypeScript type definition, exclusively for type-checking. Using `type` import is crucial to prevent runtime errors or unnecessary bundling in modern TypeScript.

Quickstart

Demonstrates defining a multi-format library configuration using `defineConfig` in a `bundlib.config.ts` file, and shows how to invoke the build via the CLI in `package.json`.

/* bundlib.config.ts */
import { defineConfig } from 'bundlib';

export default defineConfig({
  input: 'src/index.ts', // Your main entry point
  output: [
    { format: 'es', file: 'dist/index.mjs', sourcemap: true },
    { format: 'cjs', file: 'dist/index.cjs', sourcemap: true },
    { format: 'umd', file: 'dist/index.umd.js', name: 'MyLibrary', sourcemap: true }
  ],
  // Optional: Define external dependencies to prevent bundling them
  external: ['lodash'],
  // Optional: Configure TypeScript for type declarations
  project: 'tsconfig.json',
  // Optional: Enable minification for production builds
  min: process.env.NODE_ENV === 'production'
});

/* package.json */
// Add a script to your package.json
// "scripts": {
//   "build": "bundlib build",
//   "watch": "bundlib watch"
// }

// To run the build:
// npm install --save-dev bundlib rollup typescript
// npm run build