Bunli - The CLI Framework for Bun

Defines configuration for Bunli CLI projects. Used in bunli.config.ts files.

Syntax

function defineConfig(config: BunliConfigInput): BunliConfig;

Parameters

config

The configuration object for your CLI project.

interface BunliConfig {
  // Basic metadata
  name?: string;
  version?: string;
  description?: string;

  // Command configuration
  commands?: {
    entry?: string;
    directory?: string;
    generateReport?: boolean;
  };

  // Plugin configuration
  plugins?: import("@bunli/core").PluginConfig[];

  // Build configuration
  build?: {
    entry?: string | string[];
    outdir?: string;
    targets?: string[];
    compress?: boolean;
    external?: string[];
    minify?: boolean;
    sourcemap?: boolean;
  };

  // Development configuration
  dev?: {
    watch?: boolean;
    inspect?: boolean;
    port?: number;
  };

  // Test configuration
  test?: {
    pattern?: string | string[];
    coverage?: boolean;
    watch?: boolean;
  };

  // Help configuration
  help?: {
    renderer?: unknown; // Custom renderer function; z.unknown() accepts any type
  };

  // Release configuration
  release?: {
    npm?: boolean;
    github?: boolean;
    tagFormat?: string;
    conventionalCommits?: boolean;
    binary?: {
      packageNameFormat?: string;
      shimPath?: string;
    };
  };

  // Workspace configuration
  workspace?: {
    packages?: string[];
    shared?: any;
    versionStrategy?: "fixed" | "independent";
  };

  // TUI configuration (for commands using the render() path)
  tui?: {
    renderer?: {
      bufferMode?: "alternate" | "standard";
    };
    image?: {
      mode?: "off" | "auto" | "on";
      protocol?: "auto" | "kitty";
      width?: number;
      height?: number;
    };
  };
}

Examples

Basic Configuration

// bunli.config.ts
import { defineConfig } from "@bunli/core";

export default defineConfig({
  name: "my-cli",
  version: "1.0.0",
  description: "My awesome CLI tool",
});

With Build Settings

export default defineConfig({
  name: "my-cli",
  version: "1.0.0",
  build: {
    entry: "./src/cli.ts",
    outdir: "./dist",
    minify: true,
    compress: true,
    targets: ["darwin-arm64", "linux-x64", "windows-x64"],
  },
});

With Command Discovery

export default defineConfig({
  name: "my-cli",
  version: "1.0.0",
  commands: {
    entry: "./cli.ts",
    directory: "./src/commands",
  },
});

Development Configuration

export default defineConfig({
  name: "my-cli",
  version: "1.0.0",
  dev: {
    watch: true,
    inspect: true,
    port: 9229,
  },
  test: {
    pattern: ["**/*.test.ts", "**/*.spec.ts"],
    coverage: true,
  },
});

With Code Generation

export default defineConfig({
  name: "my-cli",
  version: "1.0.0",
  build: {
    entry: "./src/cli.ts",
    outdir: "./dist",
  },
});

Workspace Configuration

export default defineConfig({
  name: "my-monorepo",
  workspace: {
    packages: ["packages/*"],
    versionStrategy: "independent",
    shared: {
      // Shared config for all packages
      build: {
        minify: true,
        sourcemap: false,
      },
    },
  },
});

Configuration Options

Basic Metadata

name - CLI name (defaults to package.json name)
version - CLI version (defaults to package.json version)
description - CLI description

commands

Configure command loading:

entry - CLI entry file used for command discovery/codegen
directory - Optional fallback directory for command scanning

build

Configure production builds:

entry - Entry file(s) to build
outdir - Output directory
targets - Platform targets for multi-platform builds
compress - Compress builds with tar.gz
external - Packages to exclude from bundle
minify - Minify output (default: false)
sourcemap - Generate sourcemaps (default: true)

tui

Configure the terminal UI rendering (for commands using the render() path):

renderer.bufferMode - 'alternate' (full-screen) or 'standard' (scrollback-friendly, default)
image.mode - 'off', 'auto' (default), or 'on' — controls terminal image preview
image.protocol - 'auto' (default) or 'kitty' — image protocol to use
image.width / image.height - Terminal cell dimensions for image layout

dev

Configure development mode:

watch - Enable file watching (default: true)
inspect - Enable debugger
port - Debugger port (default: 9229)

test

Configure testing:

pattern - Test file patterns
coverage - Generate coverage reports
watch - Watch mode for tests (default: false)

release

Configure releases:

npm - Publish to npm
github - Create GitHub releases
tagFormat - Git tag format
conventionalCommits - Use conventional commits
binary.packageNameFormat - Naming template for per-platform npm packages
binary.shimPath - Path to generated ESM shim file (default: bin/run.mjs)

workspace

Configure monorepo workspaces:

packages - Glob patterns for workspace packages
shared - Configuration shared by all packages
versionStrategy - How to version packages

Usage with Bunli CLI

The configuration is automatically loaded by the bunli CLI:

# Uses build.entry from config
bunli build

# Uses dev settings from config
bunli dev

# Uses test.pattern from config
bunli test

Command-line flags override config values:

# Overrides build.minify
bunli build --minify false

# Overrides dev.port
bunli dev --port 3000

Loading Config

The bunli CLI looks for config files in this order:

bunli.config.ts
bunli.config.js
bunli.config.mjs

You can also load config programmatically:

import { loadConfig } from "@bunli/core";

const config = await loadConfig();

Automatic Loading: In most cases, you don't need to manually load config. createCLI() automatically loads from bunli.config.ts when called without arguments.

Use defineConfig for better TypeScript support. It provides type checking and autocompletion for all configuration options.

Best Practices

Keep config minimal - Only configure what differs from defaults
Use TypeScript - bunli.config.ts provides best type safety
Share workspace config - Use workspace.shared for common settings
Externalize native deps - Add binary dependencies to build.external
Enable compression - Use compress: true for distribution builds

defineConfig