0
# CLI Interface
1

2
The microbundle command-line interface provides build and watch commands with extensive configuration options for bundling JavaScript libraries from the terminal or package.json scripts.
3

4
## Capabilities
5

6
### Commands
7

8
Microbundle provides two main commands for building and developing libraries.
9

10
```bash { .api }
11
# Build command (default) - Build once and exit
12
microbundle [entries...] [options]
13
microbundle build [entries...] [options]
14

15
# Watch command - Rebuilds on any source file change
16
microbundle watch [entries...] [options]
17
```
18

19
**Usage Examples:**
20

21
```bash
22
# Basic build using package.json configuration
23
microbundle
24

25
# Build specific entry files
26
microbundle src/index.js src/cli.js
27

28
# Build with custom output formats
29
microbundle --format esm,cjs,umd
30

31
# Development mode with watch
32
microbundle watch --sourcemap
33

34
# Node.js library build
35
microbundle --target node --format cjs --no-compress
36

37
# Custom output directory
38
microbundle --output dist/bundle.js
39

40
# Build with external dependencies
41
microbundle --external react,lodash --globals react=React,lodash=_
42
```
43

44
### Global Options
45

46
Configuration options available for both build and watch commands.
47

48
```bash { .api }
49
# Entry and Output Options
50
--entry, -i, -e <files>       # Entry module(s) (comma-separated or multiple flags)
51
--output, -o, -d <path>       # Directory or file path for build output
52

53
# Format and Target Options  
54
--format, -f <formats>        # Output formats: modern,esm,cjs,umd,iife (default: modern,esm,cjs,umd)*
55
--target <env>                # Target environment: web or node (default: web)
56

57
# * Default format includes 'modern' unless MICROBUNDLE_MODERN=false environment variable is set
58

59
# Dependency Options
60
--external <deps>             # External dependencies (comma-separated) or 'none'
61
--globals <mappings>          # Global variable mappings for UMD (e.g., react=React,jquery=$)
62

63
# Optimization Options
64
--compress                    # Enable Terser compression (default: true for web, false for node)
65
--no-compress                 # Disable compression explicitly
66
--strict                      # Enforce undefined global context and "use strict"
67

68
# Development Options
69
--watch, -w                   # Enable watch mode (rebuild on changes)
70
--sourcemap                   # Generate source maps (default: true)
71
--no-sourcemap                # Disable source maps
72
--raw                         # Show raw byte sizes instead of gzipped
73

74
# Build Customization
75
--define <definitions>        # Replace constants (e.g., API_KEY=1234,@assign=Object.assign)
76
--alias <mappings>            # Module import aliases (e.g., react=preact/compat)
77
--name <globalName>           # Global name for UMD builds
78
--cwd <directory>             # Working directory (default: current directory)
79

80
# TypeScript Options
81
--tsconfig <path>             # Path to custom TypeScript configuration
82
--generateTypes               # Generate TypeScript declaration files
83
--no-generateTypes            # Disable TypeScript declaration generation
84

85
# Styling Options
86
--css <mode>                  # CSS output mode: inline or external (default: external)
87
--css-modules <config>        # CSS modules configuration
88

89
# Advanced Options
90
--workers                     # Bundle web workers using off-main-thread
91
--visualize                   # Generate bundle composition visualization (stats.html)
92
--pkg-main                    # Use package.json main entries for output paths (default: true)
93
--no-pkg-main                 # Disable package.json main entry usage
94

95
# JSX Options
96
--jsx <pragma>                # JSX pragma function (default: h)
97
--jsxFragment <pragma>        # JSX fragment pragma (default: Fragment)  
98
--jsxImportSource <source>    # JSX import source for automatic runtime
99

100
# Help and Version
101
--version, -v                 # Display version number
102
--help, -h                    # Display help information
103
```
104

105
### Package.json Integration
106

107
Microbundle automatically reads configuration from your `package.json`:
108

109
```json
110
{
111
  "name": "my-library",
112
  "source": "src/index.js",
113
  "main": "dist/index.js",
114
  "module": "dist/index.esm.js",
115
  "unpkg": "dist/index.umd.js",
116
  "types": "dist/index.d.ts",
117
  "scripts": {
118
    "build": "microbundle",
119
    "dev": "microbundle watch"
120
  },
121
  "files": ["dist", "src"]
122
}
123
```
124

125
**Package.json Fields Used:**
126

127
- `source`: Entry file path
128
- `main`: CommonJS output path
129
- `module`: ESM output path  
130
- `unpkg` or `umd:main`: UMD output path
131
- `types` or `typings`: TypeScript declarations path
132
- `exports`: Modern export map support
133
- `name`: Used for UMD global name generation
134
- `dependencies` & `peerDependencies`: Auto-detected as external
135

136
### Environment Variables
137

138
Microbundle respects certain environment variables:
139

140
```bash { .api }
141
# Control modern format inclusion
142
MICROBUNDLE_MODERN=false microbundle  # Disables modern format, uses only esm,cjs,umd
143
MICROBUNDLE_MODERN=true microbundle   # Enables modern format (default behavior)
144

145
# Set compression based on NODE_ENV (overrides target-specific defaults)
146
NODE_ENV=production microbundle   # Enables compression regardless of target
147
NODE_ENV=development microbundle  # Disables compression for faster builds
148

149
# Example: Development build with specific format
150
MICROBUNDLE_MODERN=false NODE_ENV=development microbundle --format esm,cjs
151
```
152

153
### Output Formats
154

155
Detailed format specifications and their use cases:
156

157
```bash { .api }
158
# Modern format - optimized for modern browsers supporting ES modules
159
--format modern
160
# Outputs: *.modern.js - Preserves modern syntax, smaller bundles
161

162
# ECMAScript Modules - standard import/export syntax
163
--format esm  
164
# Outputs: *.esm.js or *.module.js - For bundlers and modern Node.js
165

166
# CommonJS - Node.js require/module.exports  
167
--format cjs
168
# Outputs: *.js or *.cjs - For Node.js and older bundlers
169

170
# Universal Module Definition - works everywhere
171
--format umd
172
# Outputs: *.umd.js - For browser globals, AMD, and CommonJS
173

174
# Immediately Invoked Function Expression - direct browser usage
175
--format iife
176
# Outputs: *.iife.js - Self-executing bundle for browser script tags
177
```
178

179
### Advanced CLI Usage
180

181
**Multi-entry builds:**
182

183
```bash
184
# Build multiple entry points
185
microbundle src/index.js src/cli.js src/worker.js
186

187
# Using glob patterns (via package.json source field)
188
# package.json: "source": "src/*.js"
189
microbundle
190
```
191

192
**Custom build pipelines:**
193

194
```bash
195
# Library for browsers and Node.js
196
microbundle --format modern,esm,cjs --target web
197
microbundle src/node.js --format cjs --target node --output dist/node.js
198

199
# Development build with debugging
200
microbundle watch --sourcemap inline --no-compress --format esm
201

202
# Production build with optimization
203
microbundle --compress --no-sourcemap --visualize --format modern,esm,cjs,umd
204
```
205

206
**TypeScript projects:**
207

208
```bash
209
# Basic TypeScript build
210
microbundle src/index.ts --generateTypes
211

212
# Custom TypeScript configuration  
213
microbundle --tsconfig tsconfig.build.json --generateTypes
214

215
# Mixed JavaScript and TypeScript
216
microbundle src/index.js src/types.ts --generateTypes
217
```
218

219
**React/JSX projects:**
220

221
```bash
222
# React components with custom JSX pragma
223
microbundle --jsx React.createElement --jsxFragment React.Fragment
224

225
# Preact components
226
microbundle --jsx h --jsxFragment Fragment
227

228
# Modern automatic JSX runtime
229
microbundle --jsxImportSource react
230
```
231

232
### Error Codes and Troubleshooting
233

234
Common CLI error scenarios and solutions:
235

236
```bash
237
# Missing entry file
238
Error: No entry module found
239
# Solution: Specify --entry or add "source" field to package.json
240

241
# Unresolved dependencies  
242
Error: Could not resolve 'react'
243
# Solution: Add to --external or install as dependency
244

245
# TypeScript configuration issues
246
Error: TypeScript compilation failed
247
# Solution: Check --tsconfig path or fix TypeScript errors
248

249
# Permission issues
250
Error: EACCES: permission denied
251
# Solution: Check file permissions or use sudo (not recommended)
252
```
253

254
### Shell Integration
255

256
**Bash/Zsh completion:**
257

258
```bash
259
# Enable tab completion (if supported by your shell)
260
eval "$(microbundle --completion)"
261
```
262

263
**NPM scripts integration:**
264

265
```json
266
{
267
  "scripts": {
268
    "build": "microbundle",
269
    "build:prod": "microbundle --compress --no-sourcemap",  
270
    "build:dev": "microbundle --no-compress --sourcemap inline",
271
    "dev": "microbundle watch",
272
    "dev:node": "microbundle watch --target node --format cjs",
273
    "analyze": "microbundle --visualize",
274
    "type-check": "microbundle --generateTypes --no-compress"
275
  }
276
}
277
```
278

279
**CI/CD pipeline usage:**
280

281
```bash
282
# Continuous Integration
283
npm run build
284
# or
285
npx microbundle --format modern,esm,cjs,umd --compress
286

287
# Pre-commit hooks
288
microbundle --format esm,cjs --no-compress --sourcemap
289
```