backdy-ci

Rollup-powered bundler CLI (ci / mini-build) and TypeScript build tool with zero-config defaults, dual ESM and CommonJS output, automated declaration generation, extensible lifecycle plugins, and smart cache-busting.

Overview

backdy-ci combines the bundling and tree-shaking performance of Rollup with the transpilation speed of esbuild. It is built for TypeScript and JavaScript libraries, CLI applications, browser bundles, worker threads, and multi-entry monorepos without requiring complex configuration boilerplate.

You can execute builds using either the ci binary or the mini-build alias.

Key Features

• Zero-config defaults: Automatically detects standard entry points (src/index.ts, src/index.js, etc.) and outputs ready-to-publish bundles in dist/.
• Dual ESM and CommonJS output: Emits .mjs for ESM and .cjs for CommonJS so that the consumer's package.json "type" field never causes module resolution conflicts.
• Automated type declarations: Generates .d.ts, .d.mts, and .d.cts files with support for single bundled files or preserved module hierarchies (--single / --no-single).
• Flexible entry patterns: Supports positional arguments, -i / --input flags, brace expansion (src/{main,worker,math}.ts), recursive globs (src/**/*.ts), and custom output aliases (name=src/entry.ts).
• Worker thread compilation: Dedicated --worker flag for bundling background worker threads alongside main application entries.
• Smart cache-busting (--hex-output): Keeps main entry filenames stable for package exports while appending content hashes to internal code-split chunk files.
• Chunk directory control: Emits shared chunks into a dedicated subfolder (--chunk-dir) or flattens them into the root output directory (--flat-chunks).
• Extensible plugin system: Lifecycle hooks via MiniBuildPlugin for source transformation (onTransform), module resolution (onResolve), custom loaders (onLoad), and post-build tasks (onEnd).
• Custom tsconfig support: Pass custom tsconfig file paths or inline compilerOptions via CLI (--tsconfig) and configuration files.
• Dynamic banners and footers: Automatically injects license notices and version headers with template interpolation (${pkg.name}, ${pkg.version}, ${year}).
• Production optimization: Minification via Terser with license comment preservation (-m, --minify), sourcemaps with automatic Node.js runtime registration (-s, --sourcemap), and compile-time identifier replacements (-D, --define).
• Dual CLI and Programmatic API: Full feature parity between the standalone ci CLI utility and the programmatic Node.js API.

Requirements

• Node.js >= 18.0.0

Installation

Install backdy-ci as a development dependency:

# Using npm
npm install -D backdy-ci

# Using pnpm
pnpm add -D backdy-ci

# Using yarn
yarn add -D backdy-ci

# Using bun
bun add -D backdy-ci

Quick Start

1. Build via CLI

Bundle a library into both ESM and CommonJS with TypeScript declarations using ci (or mini-build):

# Using ci
ci build src/index.ts -f esm,cjs --dts -o dist

# Using mini-build alias
mini-build build src/index.ts -f esm,cjs --dts -o dist

2. Configure package.json Scripts

Add standard build and development scripts to your package.json:

{
  "scripts": {
    "build": "ci build src/index.ts -f esm,cjs --clean --dts -o dist",
    "dev": "ci watch src/index.ts -f esm,cjs --sourcemap -o dist"
  }
}

Configuration File (mini-build.config.ts)

For advanced pipelines, create a mini-build.config.ts or mini-build.config.js file:

import { defineConfig } from "backdy-ci";

export default defineConfig({
  entry: {
    main: "src/main.ts",
    worker: "src/worker.ts",
    "utils/math": "src/math.ts",
  },
  outDir: "dist",
  formats: ["esm", "cjs"],
  sourcemap: true,
  clean: true,
  dts: true,
  banner: `/**\n * \${pkg.name} v\${pkg.version}\n * @license MIT\n * Built © \${year}\n */`,
  tsconfig: {
    compilerOptions: {
      target: "ES2022",
      module: "ESNext",
      strict: true,
      skipLibCheck: true,
    },
  },
});

To create a starter configuration file interactively:

ci init

Custom Plugin System

backdy-ci provides an esbuild-style plugin lifecycle via MiniBuildPlugin:

import { defineConfig, type MiniBuildPlugin } from "backdy-ci";

const bannerPlugin = (bannerText: string): MiniBuildPlugin => ({
  name: "banner-plugin",
  setup(build) {
    // Transform source code matching a filter
    build.onTransform(/\.(ts|js|tsx)$/, (code, id) => {
      return `/* ${bannerText} */\n${code}`;
    });

    // Execute post-build reporting
    build.onEnd((result) => {
      console.log(
        `Build finished: ${result.outputs.length} outputs in ${result.duration}ms`,
      );
    });
  },
});

export default defineConfig({
  entry: "src/index.ts",
  outDir: "dist",
  formats: ["esm", "cjs"],
  plugins: [bannerPlugin("Copyright 2026 backady")],
});

Custom TSConfig Support

Custom TypeScript compiler options can be passed through the configuration file or directly on the CLI:

Via CLI

# Pass external tsconfig file path
ci build src/index.ts --tsconfig tsconfig.build.json

# Pass inline compilerOptions as JSON
ci build src/index.ts --tsconfig '{"compilerOptions":{"jsx":"react-jsx","target":"ES2022"}}'

Via Configuration File

export default defineConfig({
  entry: "src/index.ts",
  outDir: "dist",
  tsconfig: {
    compilerOptions: {
      jsx: "react-jsx",
      target: "ES2022",
      experimentalDecorators: true,
    },
  },
});

Programmatic API

backdy-ci can be embedded directly into custom Node.js automation scripts and build pipelines:

import { build, watch, defineConfig, definePlugin } from "backdy-ci";

// One-shot build
const result = await build({
  entry: "src/index.ts",
  outDir: "dist",
  formats: ["esm", "cjs"],
  sourcemap: true,
  dts: true,
});

console.log(
  `Build completed in ${result.duration}ms with ${result.outputs.length} files.`,
);

// Watch mode for incremental rebuilds
const watcher = await watch({
  entry: "src/index.ts",
  outDir: "dist",
});

// To stop watching when finished:
// await watcher.close();

Practical Recipes

A comprehensive guide containing 25+ copy-pasteable CLI patterns is available in CLI_EXAMPLES.md.

Selected recipes:

# Brace expansion for multiple targets
ci build -i "src/{main,worker,math}.ts" -f esm,cjs -o dist

# Deep recursive discovery
ci build -i "src/**/*.ts" -f esm -o dist

# Background worker thread bundling
ci build src/main.ts --worker src/worker.ts -f esm,cjs -o dist

# Smart cache-busting (stable entry, hashed shared chunks)
ci build -i "src/{main,worker}.ts" -f esm --hex-output -o dist

# Flat shared chunks in root output folder
ci build -i "src/{main,worker}.ts" -f esm --hex-output --flat-chunks -o dist

# Custom chunk subdirectory
ci build -i "src/{main,worker}.ts" -f esm --hex-output --chunk-dir vendor_chunks -o dist

Example Projects

The examples/ directory contains 28 standalone, ready-to-run projects demonstrating specific architectures and workflows:

See examples/README.md for individual build instructions.

Development and Testing

To develop and test locally:

# Install dependencies
pnpm install

# Compile the package
pnpm build

# Run TypeScript type check
pnpm typecheck

# Run test verification
pnpm test

License

This project is licensed under the MIT License.

Copyright (c) 2026 backady, prexjs, codewithsorabh (mini-build Authors).