Unbuild: Unified JavaScript Build System

Common errors

• Error: Missing dependency: 'package-name' or Error: Unused dependency: 'package-name'

  cause `unbuild`'s 'secure builds' feature detected an inconsistency between `package.json` dependencies and actual code usage, leading to a build failure.
  fix Update `package.json` to accurately reflect all used dependencies (add missing) or remove unused ones from `dependencies`, `devDependencies`, or `peerDependencies`.

• TypeError: (0 , unbuild__WEBPACK_IMPORTED_MODULE_0__.defineBuildConfig) is not a function

  cause Attempting to import `defineBuildConfig` using CommonJS `require()` syntax or in a context that does not correctly resolve its ESM export (e.g., in a `.js` file without `type: "module"`).
  fix Ensure `build.config.ts` (or equivalent) uses ESM `import` statements (e.g., `import { defineBuildConfig } from 'unbuild';`) and your project is configured for ESM, typically by adding `"type": "module"` to `package.json`.

• Cannot find module 'my-package/dist/index.cjs' or 'my-package/dist/index.mjs'

  cause The `exports` or `main` fields in `package.json` point to a non-existent file, or `unbuild` did not successfully generate the expected output files in the specified `outDir` (default `dist`).
  fix Verify that your `package.json` `exports`, `main`, and `types` fields correctly map to the files generated by `unbuild` (e.g., `dist/index.cjs`, `dist/index.mjs`). Run `npx unbuild` to ensure the build process completes without errors.

• Declaration file '...' is a CommonJS module, but it's used as an ES module. Consider `esModuleInterop` or changing your module resolution.

  cause TypeScript configuration (`tsconfig.json`'s `moduleResolution`, `module`, or `esModuleInterop`) is conflicting with how `unbuild` generates declaration files, especially for dual CommonJS/ESM packages.
  fix Adjust `tsconfig.json`'s `moduleResolution` and `module` options to match your project's target environment. Ensure `esModuleInterop` is enabled if needed, and confirm `unbuild`'s `declaration` option is set appropriately (e.g., `node16` for modern dual package support).

Warnings

• gotcha Unbuild maintainers are actively experimenting with 'obuild' (based on 'rolldown') as a potential next-generation successor. While unbuild remains actively maintained, users should be aware that future development focus or a transition might occur, which could impact long-term strategy for new projects.
  Fix: Monitor announcements from the 'unjs' organization for updates. For projects prioritizing raw build speed or exploring future-proof solutions, consider evaluating 'obuild'.
• gotcha Unbuild includes 'secure builds' features that perform strict checks for missing or unused dependencies defined in `package.json`. Builds will fail if inconsistencies are detected, ensuring clean dependency graphs but requiring accurate `package.json` entries.
  Fix: Thoroughly review `package.json` `dependencies`, `devDependencies`, and `peerDependencies`. Add any genuinely missing packages and remove any that are no longer used by the project to avoid build failures.
• gotcha The behavior of TypeScript declaration file generation, particularly for CommonJS default exports and modern Node.js module resolution (`.d.cts`, `.d.mts`), was refined in v3.5.0 and subsequent versions. This may lead to changes in generated type files.
  Fix: After upgrading to v3.5.0 or newer, carefully review the generated `.d.ts`, `.d.mts`, and `.d.cts` files to ensure they align with your project's expected type structure and consumption patterns. Adjust the `declaration` option in `build.config.ts` if needed.
• gotcha If you are using `composite: true` in your `tsconfig.json`, `unbuild` provides a specific workaround. Not correctly configuring or understanding this interaction can lead to build errors related to project references or declaration generation.
  Fix: If experiencing issues with `composite` projects, consult the `unbuild` documentation and GitHub issues for the recommended workaround or configuration adjustments for `tsconfig.json` to ensure compatibility.
• gotcha The `declaration` option in `build.config.ts` supports multiple values (e.g., `true`, `compatible`, `node16`, `false`, `undefined`). Misunderstanding these options can lead to incorrect or incomplete type declaration file outputs for different module systems.
  Fix: Carefully choose the `declaration` option value based on your target environment and desired declaration file structure. For modern Node.js environments supporting dual CommonJS and ESM packages, `node16` is often the appropriate choice to generate both `.d.mts` and `.d.cts`.

Install

• npm install unbuild npm
• yarn add unbuild yarn
• pnpm add unbuild pnpm

Imports

• defineBuildConfig
  wrong:

  const { defineBuildConfig } = require('unbuild')

  correct:

  import { defineBuildConfig } from 'unbuild'

  `defineBuildConfig` is an ESM export used in `build.config.ts` for configuration. The main build process is typically run via CLI (`npx unbuild`), not by importing this function to trigger a build directly.
• build

  import { build } from 'unbuild'

  While `unbuild` is primarily CLI-driven, programmatic usage of the `build` function is possible for advanced integrations. Consult the official documentation for detailed programmatic API usage.
• BuildEntry

  import type { BuildEntry, BuildConfig } from 'unbuild'

  Import types like `BuildEntry` or `BuildConfig` for strong typing when defining custom build configurations in TypeScript.

Quickstart

Demonstrates how to set up `unbuild` for a TypeScript project, including `src/index.ts`, the necessary `package.json` fields, an optional `build.config.ts`, and how to trigger the build from the command line.

import { defineBuildConfig } from 'unbuild';

// 1. Create src/index.ts
// This is your main entry point.
// export const log = (...args: any[]) => {
//   console.log('Hello from unbuild:', ...args);
// };

// 2. Update package.json (example excerpt):
/*
{
  "name": "my-cool-lib",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "unbuild",
    "prepack": "unbuild" // Good practice to build before packing
  },
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}
*/

// 3. (Optional) Create build.config.ts for custom configuration:
// This file specifies build entries, output directory, etc.
export default defineBuildConfig({
  entries: [
    // Default entry point
    './src/index',
    // Example for mkdist bundleless build
    {
      builder: 'mkdist',
      input: './src/components/',
      outDir: './dist/components'
    }
  ],
  outDir: 'dist',
  declaration: true, // Generates .d.ts files
  clean: true // Cleans output directory before build
});

// 4. Run the build from your terminal:
// npx unbuild

// 5. Example usage of the built library (e.g., in another project):
// import { log } from 'my-cool-lib'; // Assuming `my-cool-lib` is installed
// log('Building amazing things!');

// const { log: cjsLog } = require('my-cool-lib');
// cjsLog('CJS module loaded!');