Skip to main content

​
Function signature

packages/core/src/config.ts:173-175
export function defineConfig(config: BunliConfigInput): BunliConfig {
  return bunliConfigSchema.parse(config)
}
A helper function for defining Bunli configuration with full type safety. It validates the configuration using Zod and applies all default values.

​
Parameters

​
config
BunliConfigInput
required
Configuration object for the CLI application.

​
Return value

​
BunliConfig
BunliConfig
Validated configuration object with all defaults applied.

​
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 commands configuration

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

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI tool',
  commands: {
    entry: './src/cli.ts',
    directory: './src/commands',
    generateReport: true
  }
})

​
With build configuration

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

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

​
With plugins

bunli.config.ts
import { defineConfig } from '@bunli/core'
import { completionsPlugin } from '@bunli/plugin-completions'
import { configPlugin } from '@bunli/plugin-config'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  plugins: [
    completionsPlugin(),
    configPlugin({
      name: 'my-cli',
      searchPlaces: ['.my-cli.json', '.my-clirc']
    })
  ]
})

​
Development and testing

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

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

​
Workspace configuration

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

export default defineConfig({
  name: 'my-monorepo',
  version: '1.0.0',
  workspace: {
    packages: ['packages/*'],
    versionStrategy: 'independent'
  }
})

​
Release configuration

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

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  release: {
    npm: true,
    github: true,
    tagFormat: 'v{{version}}',
    conventionalCommits: true,
    binary: {
      packageNameFormat: '{{name}}-{{platform}}',
      shimPath: 'bin/run.mjs'
    }
  },
  build: {
    targets: ['node-linux-x64', 'node-darwin-arm64']
  }
})

​
Custom TUI configuration

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

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  tui: {
    renderer: {
      bufferMode: 'alternate' // Full-screen TUI
    }
  }
})

​
Custom help renderer

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

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  help: {
    renderer({ cliName, version, command, commands, terminal }) {
      console.log(`${cliName} v${version}`)
      
      if (command) {
        console.log(`\nCommand: ${command.name}`)
        console.log(command.description)
      } else {
        console.log('\nCommands:')
        for (const cmd of commands) {
          console.log(`  ${cmd.name.padEnd(20)} ${cmd.description}`)
        }
      }
    }
  }
})

​
Configuration file formats

Bunli supports multiple configuration file formats:
bunli.config.ts
import { defineConfig } from '@bunli/core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0'
})

​
JavaScript (ESM)

bunli.config.mjs
import { defineConfig } from '@bunli/core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0'
})

​
JavaScript (CommonJS)

bunli.config.js
const { defineConfig } = require('@bunli/core')

module.exports = defineConfig({
  name: 'my-cli',
  version: '1.0.0'
})

​
Validation

The defineConfig function validates the configuration using Zod schemas. If validation fails, it throws an error with details: 
// Invalid configuration
defineConfig({
  name: '',  // Empty string not allowed
  version: '1.0.0'
})
// Error: Invalid config: { name: ['String must contain at least 1 character(s)'] }

​
Default values

The function automatically applies defaults for optional fields: 
const config = defineConfig({
  name: 'my-cli',
  version: '1.0.0'
})

// Defaults applied:
// config.build.targets = []
// config.build.compress = false
// config.build.minify = false
// config.build.sourcemap = true
// config.dev.watch = true
// config.dev.inspect = false
// config.test.pattern = ['**/*.test.ts', '**/*.spec.ts']
// config.test.coverage = false
// config.test.watch = false
// config.workspace.versionStrategy = 'fixed'
// config.release.npm = true
// config.release.github = false
// config.release.tagFormat = 'v{{version}}'
// config.release.conventionalCommits = true
// config.plugins = []

Build docs developers (and LLMs) love

Get started for freeTalk to us