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
```