unbuild

A unified javascript build system

Building tool
unjs/unbuildunbuild

README

unbuild


A unified javascript build system


📦 Optimized bundler


Robust rollup based bundler that supports typescript and generates commonjs and module formats + type declarations.

🪄 Automated config


Automagically infer build config and entries from package.json.

📁 Bundleless build


Integration with mkdist for generating bundleless dists with file-to-file transpilation.

✨ Passive watcher


Stub dist once using jiti and you can try and link your project without needing to watch and rebuild during development.

✍ Untype Generator


Integration with untyped.

✔️ Secure builds


Automatically check for various build issues such as potential missing and unused dependencies and fail CI.

CLI output also includes output size and exports for quick inspection.

Usage


Create src/index.ts:

  1. ```ts
  2. export const log = (...args) => {
  3.   console.log(...args);
  4. };
  5. ```

Update package.json:

  1. ```json
  2. {
  3.   "type": "module",
  4.   "exports": {
  5.     ".": {
  6.       "import": "./dist/index.mjs",
  7.       "require": "./dist/index.cjs"
  8.     }
  9.   },
  10.   "main": "./dist/index.cjs",
  11.   "types": "./dist/index.d.ts",
  12.   "files": ["dist"]
  13. }
  14. ```

Note

You can find a more complete example in unjs/template for project setup.


Build with unbuild:

  1. ```sh
  2. npx unbuild
  3. ```

Configuration is automatically inferred from fields in package.json mapped to src/ directory. For more control, continue with next section.

Configuration


Create build.config.ts:

  1. ```ts
  2. export default {
  3.   entries: ["./src/index"],
  4. };
  5. ```

You can either use unbuild key in package.json or build.config.{js,cjs,mjs,ts,mts,cts,json} to specify configuration.

See options here.

Example:

  1. ```ts
  2. import { defineBuildConfig } from "unbuild";

  4. export default defineBuildConfig({
  5.   // If entries is not provided, will be automatically inferred from package.json
  6.   entries: [
  7.     // default
  8.     "./src/index",
  9.     // mkdist builder transpiles file-to-file keeping original sources structure
  10.     {
  11.       builder: "mkdist",
  12.       input: "./src/package/components/",
  13.       outDir: "./build/components",
  14.     },
  15.   ],

  17.   // Change outDir, default is 'dist'
  18.   outDir: "build",

  20.   // Generates .d.ts declaration file
  21.   declaration: true,
  22. });
  23. ```

Or with multiple builds you can declare an array of configs:

  1. ```ts
  2. import { defineBuildConfig } from "unbuild";

  4. export default defineBuildConfig([
  5.   {
  6.     // If entries is not provided, will be automatically inferred from package.json
  7.     entries: [
  8.       // default
  9.       "./src/index",
  10.       // mkdist builder transpiles file-to-file keeping original sources structure
  11.       {
  12.         builder: "mkdist",
  13.         input: "./src/package/components/",
  14.         outDir: "./build/components",
  15.       },
  16.     ],

  18.     // Change outDir, default is 'dist'
  19.     outDir: "build",

  21.     /**
  22.      * * `compatible` means "src/index.ts" will generate "dist/index.d.mts", "dist/index.d.cts" and "dist/index.d.ts".
  23.      * * `node16` means "src/index.ts" will generate "dist/index.d.mts" and "dist/index.d.cts".
  24.      * * `true` is equivalent to `compatible`.
  25.      * * `false` will disable declaration generation.
  26.      * * `undefined` will auto detect based on "package.json". If "package.json" has "types" field, it will be `"compatible"`, otherwise `false`.
  27.      */
  28.     declaration: "compatible",
  29.   },
  30.   {
  31.     name: "minified",
  32.     entries: ["./src/index"],
  33.     outDir: "build/min",
  34.     rollup: {
  35.       esbuild: {
  36.         minify: true,
  37.       },
  38.     },
  39.   },
  40. ]);
  41. ```

💻 Development


- Clone this repository
- Enable Corepack usingcorepack enable (use npm i -g corepack for Node.js < 16.10)
- Install dependencies using pnpm install
- Run interactive tests using pnpm dev