API Reference
defineConfig
Define configuration for Bunli CLI projects
defineConfig
Defines configuration for Bunli CLI projects. Used in bunli.config.ts files.
Syntax
function defineConfig(config: BunliConfig): BunliConfigParameters
config
The configuration object for your CLI project.
interface BunliConfig {
// Basic metadata
name?: string
version?: string
description?: string
// Command configuration
commands?: {
manifest?: string
directory?: string
}
// 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
}
// Code generation configuration
codegen?: {
enabled?: boolean
commandsDir?: string
output?: string
watch?: boolean
}
// Test configuration
test?: {
pattern?: string | string[]
coverage?: boolean
watch?: boolean
}
// Release configuration
release?: {
npm?: boolean
github?: boolean
tagFormat?: string
conventionalCommits?: boolean
}
// Workspace configuration
workspace?: {
packages?: string[]
shared?: any
versionStrategy?: 'fixed' | 'independent'
}
}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 Manifest
export default defineConfig({
name: 'my-cli',
version: '1.0.0',
commands: {
manifest: './src/commands/index.ts'
}
})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:
manifest- Path to command manifest file for lazy loadingdirectory- Directory to auto-discover commands (not recommended for production)
Example manifest:
// src/commands/index.ts
export default {
build: () => import('./build.js'),
test: () => import('./test.js'),
deploy: () => import('./deploy.js')
}build
Configure production builds:
entry- Entry file(s) to buildoutdir- Output directory (default:./dist)targets- Platform targets for multi-platform buildscompress- Compress builds with tar.gzexternal- Packages to exclude from bundleminify- Minify output (default: true)sourcemap- Generate sourcemaps
dev
Configure development mode:
watch- Enable file watching (default: true)inspect- Enable debuggerport- Debugger port (default: 9229)
test
Configure testing:
pattern- Test file patternscoverage- Generate coverage reportswatch- Watch mode for tests
release
Configure releases (planned feature):
npm- Publish to npmgithub- Create GitHub releasestagFormat- Git tag formatconventionalCommits- Use conventional commits
workspace
Configure monorepo workspaces:
packages- Glob patterns for workspace packagesshared- Configuration shared by all packagesversionStrategy- 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 testCommand-line flags override config values:
# Overrides build.minify
bunli build --no-minify
# Overrides dev.port
bunli dev --port 3000Loading Config
The bunli CLI looks for config files in this order:
bunli.config.tsbunli.config.jsbunli.config.mjs
You can also load config programmatically:
import { loadConfig } from '@bunli/core'
const config = await loadConfig()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.tsprovides best type safety - Share workspace config - Use
workspace.sharedfor common settings - Externalize native deps - Add binary dependencies to
build.external - Enable compression - Use
compress: truefor distribution builds
See Also
- bunli CLI - Using the Bunli CLI
- Configuration - Configuration concepts
- Build & Distribution - Building for production