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): BunliConfig
Parameters
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
}
// 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
}
})
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 test
Command-line flags override config values:
# Overrides build.minify
bunli build --no-minify
# 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'
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.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
See Also
- bunli CLI - Using the Bunli CLI
- Configuration - Configuration concepts
- Build & Distribution - Building for production