0
# Bunli
1

2
Bunli is a comprehensive CLI development framework specifically designed for Bun runtime. It provides a complete toolchain for building, testing, and distributing command-line applications with type-safe command definitions, development tools with hot reloading, and compilation to standalone binaries for multiple platforms.
3

4
## Package Information
5

6
- **Package Name**: bunli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `bun add bunli` or `npm install bunli`
10
- **Bun Requirement**: >=1.0.0
11

12
## Core Imports
13

14
```typescript
15
import { defineConfig, loadConfig, findEntry, type BunliConfig } from 'bunli';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { defineConfig, loadConfig, findEntry } = require('bunli');
22
```
23

24
## Basic Usage
25

26
```typescript
27
// bunli.config.ts
28
import { defineConfig } from 'bunli';
29

30
export default defineConfig({
31
  name: 'my-cli',
32
  version: '1.0.0',
33
  build: {
34
    entry: 'src/cli.ts',
35
    targets: ['native']
36
  },
37
  dev: {
38
    watch: true
39
  }
40
});
41

42
// Using programmatic API
43
import { loadConfig, findEntry } from 'bunli';
44

45
const config = await loadConfig();
46
const entryPoint = await findEntry();
47
```
48

49
## Architecture
50

51
Bunli is built around several key components:
52

53
- **CLI Framework**: Built on @bunli/core for type-safe command definitions and execution
54
- **Development Tools**: Hot reload, debugging, and test execution capabilities
55
- **Build System**: Compilation to standalone executables for multiple platforms using Bun's native compiler
56
- **Configuration System**: Type-safe configuration with auto-detection and validation
57
- **Workspace Support**: Multi-package monorepo support with independent or fixed versioning strategies
58
- **Programmatic API**: Functions for configuration management and project introspection
59

60
## Capabilities
61

62
### Configuration Management
63

64
Type-safe configuration system for defining project settings, build options, and development preferences.
65

66
```typescript { .api }
67
/**
68
 * Type-safe helper for defining bunli configuration files
69
 * @param config - Configuration object following BunliConfig schema
70
 * @returns The same configuration object with type validation
71
 */
72
function defineConfig(config: BunliConfig): BunliConfig;
73

74
/**
75
 * Loads bunli configuration from config files
76
 * @param cwd - Current working directory to search for config files (defaults to process.cwd())
77
 * @returns Promise resolving to the loaded configuration
78
 */
79
function loadConfig(cwd?: string): Promise<BunliConfig>;
80

81
interface BunliConfig {
82
  name?: string;
83
  version?: string;
84
  description?: string;
85
  commands?: {
86
    manifest?: string;
87
    directory?: string;
88
  };
89
  build?: BuildConfig;
90
  dev?: DevConfig;
91
  test?: TestConfig;
92
  release?: ReleaseConfig;
93
  workspace?: WorkspaceConfig;
94
}
95
```
96

97
[Configuration](./configuration.md)
98

99
### Project Utilities
100

101
Utilities for project introspection and file discovery.
102

103
```typescript { .api }
104
/**
105
 * Auto-detects entry point files for CLI projects
106
 * @param cwd - Current working directory to search (defaults to process.cwd())
107
 * @returns Promise resolving to detected entry file path or undefined if none found
108
 */
109
function findEntry(cwd?: string): Promise<string | undefined>;
110
```
111

112
[Project Utilities](./project-utilities.md)
113

114
### CLI Commands
115

116
Complete command-line interface for development, building, testing, and releasing CLI applications.
117

118
```bash { .api }
119
# Development
120
bunli dev [options]              # Run CLI in development mode with hot reload
121
bunli build [options]            # Build CLI for production
122
bunli test [options]             # Run tests for CLI
123

124
# Project Management
125
bunli init [options] [name]      # Initialize new Bunli CLI project
126
bunli release [options]          # Create a release of CLI
127

128
# Global Options
129
bunli --help                     # Show help information
130
bunli --version                  # Show version information
131
```
132

133
[CLI Commands](./cli-commands.md)
134

135
## Types
136

137
```typescript { .api }
138
interface BuildConfig {
139
  entry?: string | string[];
140
  outdir?: string;
141
  targets?: string[];
142
  compress?: boolean;
143
  external?: string[];
144
  minify?: boolean;
145
  sourcemap?: boolean;
146
}
147

148
interface DevConfig {
149
  watch?: boolean;
150
  inspect?: boolean;
151
  port?: number;
152
}
153

154
interface TestConfig {
155
  pattern?: string | string[];
156
  coverage?: boolean;
157
  watch?: boolean;
158
}
159

160
interface ReleaseConfig {
161
  npm?: boolean;
162
  github?: boolean;
163
  tagFormat?: string;
164
  conventionalCommits?: boolean;
165
}
166

167
interface WorkspaceConfig {
168
  packages?: string[];
169
  shared?: any;
170
  versionStrategy?: 'fixed' | 'independent';
171
}
172
```