CLI tool
unjs/unbuild avatar
unjs/unbuild

unbuild nominates its own rolldown based successor, and the last tag is a year old

📦 A unified JavaScript build system

2,727 stars110 forksTypeScriptMIT

At a glance

What is it?
unbuild is a rollup based bundler that infers its configuration from package.json and can fail your CI over an unused dependency. Its README already points readers at obuild, and the newest release tag predates the last push by more than a year.
Who is it for?
unbuild fits library authors who want zero config inference from the package.json fields they already publish and a CI check that catches missing or unused dependencies. Two things to weigh first: the tool is ESM only, so a CommonJS build script cannot require it, and the people who maintain it have already named obuild, built on rolldown, as the next generation.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unjs/unbuild2,727 ★ · +1
Star history
Repository2026-10-042026-11-16
unjs/unbuild2.7k2.7k

1 Stars in the last 43 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The README nominates obuild as the rolldown based successor

The first block after the title is a note, not a feature list, and it is about leaving. The maintainers are experimenting with obuild as the next next-gen successor based on rolldown, and readers who mainly need faster build speeds and do not mind trying beta software are pointed at it. That is the only sentence in the file about where the project is going, and it sits above everything else. The distinction matters because unbuild itself bundles with rollup, pinned in the manifest at 4.57.1 or later, and rolldown is a different bundler. So the two projects are not a drop-in swap of versions; the successor changes the tool underneath. Anyone starting a new library today has a reason to read obuild's README before committing to a config file in unbuild.

The newest release tag is thirteen months older than the last push

The release history has three entries and they stop. v3.5.0 was published 2025-02-26, v3.6.0 on 2025-07-23, and v3.6.1 on 2025-08-15, and the manifest still reads 3.6.1, so the working tree agrees with the last tag on version. The last push is dated 2026-09-23. That is more than thirteen months of commits past the newest tag, and no tag, no changelog entry, and no version bump in the manifest. The release script explains how a version would move: it runs the test suite, then changelogen with --release and --publish, then pushes with --follow-tags. So publishing is automated but manual in the sense that somebody has to run the script, and nothing in the repository forces it. For a tool that ends up in your build path, that gap is worth knowing before you treat the absence of a new tag as evidence of stability.

unbuild is ESM only while asking consumers to ship both formats

Look at the two package.json files side by side and the asymmetry is immediate. The one unbuild asks you to write declares both output formats:

json
{
  "type": "module",
  "scripts": {
    "build": "unbuild",
    "prepack": "unbuild"
  },
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

The one unbuild publishes for itself declares type module and an exports map with only two keys, types pointing at ./dist/index.d.mts and default at ./dist/index.mjs. There is no require condition and no main field. So a CommonJS project can run the binary with npx unbuild, but cannot require the module. The declaration file is .d.mts rather than the .d.ts the example consumer config uses, which is the other half of the same single-format decision.

unbuild builds itself by running its own CLI through jiti

The build script in the manifest is pnpm unbuild, and the unbuild script it calls is jiti ./src/cli. The tool compiles itself by loading its own TypeScript CLI entry through jiti at build time, and prepack runs the same thing, so a publish triggers a full self build. The stub route is wired up the same way: the stub script is pnpm unbuild --stub, which is the passive watcher feature from the README, a dist made of jiti stubs so you can link a package into another project and use it without a watch process rebuilding on every save. The repository does not use its own dist to build its own dist, which is why jiti appears in both the runtime dependencies and the self build path. Contributors reach for pnpm, and the lockfile in the tree is a pnpm one, while consumers are told to run npx unbuild.

prettier checks src, test, and examples but not the root configs

The lint script is eslint . followed by prettier -c src test examples. The eslint half covers everything, but the prettier half names three directories and stops there, so the root level configuration files that also appear in the tree are outside its range: build.config.ts, vitest.config.ts, eslint.config.mjs, tsconfig.json, and .prettierrc itself. Nothing enforces their formatting. The fix script has the same gap and adds one more oddity: it runs automd first, then eslint --fix, then prettier -w, which formats after linting rather than before. automd is what generates the badge block at the top of the README, fenced by automd:badges markers, so those badges are build output and not something you hand edit. The test script chains the whole thing together as pnpm lint, then pnpm test:types running tsc --noEmit, then vitest with coverage.

mkdist and untyped are hard dependencies, not optional integrations

Two of the README's headline features are presented as integrations. Bundleless build is integration with mkdist for generating dists with file-to-file transpilation, and the untype generator is integration with untyped. In the manifest neither is optional. mkdist sits in dependencies at 2.4.1 or later and untyped at 2.0.0 or later, alongside a full rollup plugin set of alias, commonjs, json, node-resolve, replace, and pluginutils, plus rollup-plugin-dts, esbuild, mlly, pkg-types, scule, citty, consola, defu, hookable, magic-string, pathe, tinyglobby, pretty-bytes, and a package named fix-dts-default-cjs-exports that exists to repair default CJS exports in declaration files. Twenty four runtime dependencies for a build tool, and the two builders you are least likely to use are installed whether or not you touch them.

The secure-builds check can fail CI over an unused dependency

One feature is described as secure builds, and the mechanism is worth reading closely, because it makes the build itself a linter. unbuild automatically checks for build issues such as potential missing and unused dependencies, and fails CI. Missing means something you import is not in package.json, which most bundlers warn about quietly. Unused means the reverse, an entry you declared and never imported, which turns a stale line in package.json into a red build rather than a warning. That is a real advantage for a published library, where a dependency you import but forget to declare breaks consumers at install time. It is also a behaviour change to be ready for: a package.json carried over from another project can fail its first unbuild run for a reason that has nothing to do with the code being built. The CLI also prints output size and exports for inspection, formatted with pretty-bytes.

The compatible flag is documented in a comment that stops mid path

Configuration can go in a unbuild key inside package.json or in a build.config file, and seven extensions are accepted for the latter: js, cjs, mjs, ts, mts, cts, and json. Multiple builds are declared as an array of configs. The example array carries a documentation comment for the compatible option that reads that it means src/index.ts will generate dist/index.d.mts, and then the next path begins with dist/in and the sentence stops there, without closing the quotation or explaining what the second filename is. That block is the only description of the flag in the file. The option reference itself is not a documentation page either; the README sends you to ./src/types.ts, so the authoritative list of options is a TypeScript source file in the repository. Three worked examples sit in the tree as numbered directories, zero config, mkdist, and untyped.

Editorial conclusion

unbuild fits library authors who want zero config inference from the package.json fields they already publish and a CI check that catches missing or unused dependencies. Two things to weigh first: the tool is ESM only, so a CommonJS build script cannot require it, and the people who maintain it have already named obuild, built on rolldown, as the next generation. Run npx unbuild against a throwaway package.json before you move a real build onto it, because a misjudged entry list will overwrite dist, and read the unused-dependency check, since it turns a stale entry in package.json into a red build.

Frequently asked questions

Does unbuild need a build.config file?

No. Configuration is inferred automatically from fields in package.json mapped to the src/ directory, and entries are inferred from package.json when they are not provided. A build.config file in one of seven extensions is for when you want more control, and options are documented by pointing at src/types.ts.

What output formats does unbuild produce?

CommonJS and module formats plus type declarations, from a rollup based bundler that supports TypeScript. The package.json unbuild asks consumers to write points an import condition at ./dist/index.mjs and a require condition at ./dist/index.cjs. unbuild's own published package ships only a default condition and an ESM declaration file, ./dist/index.d.mts.

How do I run unbuild without a watch process during development?

Stub the dist once with unbuild --stub, which is powered by jiti. The README describes this as a passive watcher: you can link your project and try it without watching and rebuilding. The repository uses the same route in its own package.json, where the stub script is pnpm unbuild --stub.

Can unbuild fail a build for an unused dependency?

Yes. The feature described as secure builds automatically checks for issues such as potential missing and unused dependencies and fails CI, so a dependency declared in package.json but never imported will stop the build. The CLI also reports output size and the exports it produced.

Is unbuild being replaced?

The README opens with a note that the maintainers are experimenting with obuild as the next next-gen successor based on rolldown, and suggests trying it if you mainly need faster build speeds and will accept beta software. unbuild itself bundles with rollup, so the successor changes the bundler underneath rather than only the version.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. unjs/unbuild on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unjs-unbuild.svg)](https://hysenlabs.com/projects/unjs-unbuild)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unjs-unbuild.svg)](https://hysenlabs.com/projects/unjs-unbuild)

Was this useful?