Registry / devops / unbuild

unbuild

JSON →
library3.6.1jsnpmunverified

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.

npm install unbuild
INSTALL
IMPORT
SIG · UNBUILD
U
unbuild
devopsjavascriptv3.6.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineBuildConfig
import { defineBuildConfig } from 'unbuild'
const { defineBuildConfig } = require('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.

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!');
unbuild --version
Debug
Known issues
gotchaUnbuild 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'.
affects: >=3.0.0
gotchaUnbuild 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.
affects: >=3.0.0
gotchaThe 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.
affects: >=3.5.0
gotchaIf 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.
affects: >=3.4.0
gotchaThe `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`.
affects: >=3.1.0
Errors
Common errors & fixes
Error: Missing dependency: 'package-name' or Error: Unused dependency: 'package-name'
`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
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'
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.
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).
Upgrade
Version history
3.6.1latest on npm
Audit
Dependencies
typescriptrequiredPeer dependency required for TypeScript compilation and declaration file generation.
Agent activity
6 hits · last 30 days
node
6
Resources
unbuild — npm install unbuild · libregistry