herb-build

1.4.8 verified Sat May 09 auth: no javascript

herb-build is a build tool for JavaScript/TypeScript projects with a focus on simplicity and convention over configuration. As of version 1.4.8 (stable, released monthly), it provides a single-command build pipeline that handles TypeScript compilation, bundling, and minification. Unlike Webpack or Rollup, herb-build aims to be zero-config for standard projects while still offering extensibility via plugins. It supports both ESM and CJS output, includes built-in type checking, and is designed for both CLI and programmatic use. The package has TypeScript definitions bundled and is available on npm, targeting Node.js environments.

Common errors

error Error: Cannot find module 'herb-build' ↓

cause Package not installed or import path incorrect; herb-build is not a global install.

fix

Run 'npm install herb-build --save-dev' and ensure import/require uses correct path.

error TypeError: build is not a function ↓

cause Default import used instead of named import. herb-build exports named 'build', not default.

fix

Use import { build } from 'herb-build' instead of import build from 'herb-build'.

error Error: Unknown option 'format'. Did you mean 'formats'? ↓

cause Option was renamed in v1.4.0 from 'format' to 'formats' (or becomes array).

fix

Use 'formats' (plural) with an array value, e.g., formats: ['esm'].

Warnings

breaking In v1.4.0, the 'format' option was changed from a string to an array of formats. Specifying a single string no longer works. ↓

fix Update format to an array, e.g., format: ['esm'] (or ['cjs']), or omit to use defaults.

danger In v1.2.0, the 'sourcemap' default changed from 'inline' to 'external'. This may expose source code in production if external maps are deployed. ↓

fix Set sourcemap: 'inline' for production if you need to avoid external files, or ensure .map files are not served publicly.

gotcha TypeScript declarations are only generated if the 'types' option is true (default false). Set to true to emit .d.ts files. ↓

fix Include types: true in the build options.

gotcha The built output will contain CommonJS wrapper unless format explicitly includes 'esm'. Default format is ['cjs'] which may not be tree-shakeable by bundlers. ↓

fix Specify format: ['esm'] for modern bundlers or format: ['cjs', 'esm'] for dual output.

Install

npm install herb-build

yarn add herb-build

pnpm add herb-build

Imports

build
wrong
```
const build = require('herb-build')
```
correct
```
import { build } from 'herb-build'
```
herb-build is ESM-only; CommonJS require() is not supported.

createConfig

wrong

import createConfig from 'herb-build'

correct

import { createConfig } from 'herb-build'

createConfig is a named export, not a default export.

defineConfig

wrong

import { defineConfig } from 'herb-build/config'

correct

import { defineConfig } from 'herb-build'

defineConfig is exported from the main package, not a submodule.

Quickstart

Demonstrates basic usage of the build function with TypeScript input, ESM output, minification, and type declaration generation.

// Build script for modern JS/TS projects
import { build } from 'herb-build';

// Minimal config: no options needed for defaults
const result = await build({
  input: 'src/index.ts',
  output: 'dist',
  format: 'esm',
  minify: true,
  types: true,
});

console.log('Build completed:', result.output);