{"id":12275,"library":"unbuild","title":"Unbuild: Unified JavaScript Build System","description":"Unbuild is a robust, unified JavaScript build system leveraging Rollup for efficient bundling. It targets current Node.js and browser environments, producing CommonJS, ES module, and TypeScript declaration outputs. Currently at version 3.6.1, unbuild sees active development with frequent patch and minor releases. Key differentiators include automated configuration inference from `package.json`, support for bundleless distribution via `mkdist`, a passive watcher using `jiti` for rapid development cycles, and integrated 'secure builds' that detect and report missing or unused dependencies. It also features integration with `untyped` for schema generation. While actively maintained, the project has also announced experimentation with `obuild` as a potential next-generation successor, which users should be aware of for future planning.","status":"active","version":"3.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/unbuild","tags":["javascript","typescript"],"install":[{"cmd":"npm install unbuild","lang":"bash","label":"npm"},{"cmd":"yarn add unbuild","lang":"bash","label":"yarn"},{"cmd":"pnpm add unbuild","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for TypeScript compilation and declaration file generation.","package":"typescript","optional":false}],"imports":[{"note":"`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.","wrong":"const { defineBuildConfig } = require('unbuild')","symbol":"defineBuildConfig","correct":"import { defineBuildConfig } from 'unbuild'"},{"note":"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.","symbol":"build","correct":"import { build } from 'unbuild'"},{"note":"Import types like `BuildEntry` or `BuildConfig` for strong typing when defining custom build configurations in TypeScript.","symbol":"BuildEntry","correct":"import type { BuildEntry, BuildConfig } from 'unbuild'"}],"quickstart":{"code":"import { defineBuildConfig } from 'unbuild';\n\n// 1. Create src/index.ts\n// This is your main entry point.\n// export const log = (...args: any[]) => {\n//   console.log('Hello from unbuild:', ...args);\n// };\n\n// 2. Update package.json (example excerpt):\n/*\n{\n  \"name\": \"my-cool-lib\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"build\": \"unbuild\",\n    \"prepack\": \"unbuild\" // Good practice to build before packing\n  },\n  \"exports\": {\n    \".\": {\n      \"import\": \"./dist/index.mjs\",\n      \"require\": \"./dist/index.cjs\",\n      \"types\": \"./dist/index.d.ts\"\n    }\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"files\": [\"dist\"]\n}\n*/\n\n// 3. (Optional) Create build.config.ts for custom configuration:\n// This file specifies build entries, output directory, etc.\nexport default defineBuildConfig({\n  entries: [\n    // Default entry point\n    './src/index',\n    // Example for mkdist bundleless build\n    {\n      builder: 'mkdist',\n      input: './src/components/',\n      outDir: './dist/components'\n    }\n  ],\n  outDir: 'dist',\n  declaration: true, // Generates .d.ts files\n  clean: true // Cleans output directory before build\n});\n\n// 4. Run the build from your terminal:\n// npx unbuild\n\n// 5. Example usage of the built library (e.g., in another project):\n// import { log } from 'my-cool-lib'; // Assuming `my-cool-lib` is installed\n// log('Building amazing things!');\n\n// const { log: cjsLog } = require('my-cool-lib');\n// cjsLog('CJS module loaded!');","lang":"typescript","description":"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."},"warnings":[{"fix":"Monitor announcements from the 'unjs' organization for updates. For projects prioritizing raw build speed or exploring future-proof solutions, consider evaluating 'obuild'.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.4.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update `package.json` to accurately reflect all used dependencies (add missing) or remove unused ones from `dependencies`, `devDependencies`, or `peerDependencies`.","cause":"`unbuild`'s 'secure builds' feature detected an inconsistency between `package.json` dependencies and actual code usage, leading to a build failure.","error":"Error: Missing dependency: 'package-name' or Error: Unused dependency: 'package-name'"},{"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`.","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\"`).","error":"TypeError: (0 , unbuild__WEBPACK_IMPORTED_MODULE_0__.defineBuildConfig) is not a function"},{"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.","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`).","error":"Cannot find module 'my-package/dist/index.cjs' or 'my-package/dist/index.mjs'"},{"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).","cause":"TypeScript configuration (`tsconfig.json`'s `moduleResolution`, `module`, or `esModuleInterop`) is conflicting with how `unbuild` generates declaration files, especially for dual CommonJS/ESM packages.","error":"Declaration file '...' is a CommonJS module, but it's used as an ES module. Consider `esModuleInterop` or changing your module resolution."}],"ecosystem":"npm"}