0
# Microbundle
1

2
Microbundle is a zero-configuration bundler for tiny JavaScript libraries, powered by Rollup. It automatically generates multiple output formats (CommonJS, ESM, UMD, and modern) from a single source with minimal setup, supporting TypeScript, JSX, CSS processing, and modern JavaScript features out of the box.
3

4
## Package Information
5

6
- **Package Name**: microbundle
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support)
9
- **Installation**: `npm install -D microbundle`
10

11
## Core Imports
12

13
For programmatic usage:
14

15
```javascript
16
import microbundle from "microbundle";
17
```
18

19
CommonJS:
20

21
```javascript
22
const microbundle = require("microbundle");
23
```
24

25
## Basic Usage
26

27
### CLI Usage (Most Common)
28

29
Add to your `package.json`:
30

31
```json
32
{
33
  "source": "src/index.js",
34
  "main": "dist/index.js",
35
  "module": "dist/index.esm.js",
36
  "scripts": {
37
    "build": "microbundle",
38
    "dev": "microbundle watch"
39
  }
40
}
41
```
42

43
Build your library:
44

45
```bash
46
npm run build
47
```
48

49
### Programmatic Usage
50

51
```javascript
52
import microbundle from "microbundle";
53

54
// Basic build
55
const result = await microbundle({
56
  entries: ["src/index.js"],
57
  format: "modern,esm,cjs,umd",
58
  output: "dist/bundle.js"
59
});
60

61
console.log(result.output);
62
```
63

64
## Architecture
65

66
Microbundle is built around several key components:
67

68
- **Core Bundler**: Main `microbundle()` function that orchestrates the build process using Rollup
69
- **CLI Interface**: Command-line tool with `build` and `watch` commands and extensive configuration options
70
- **Plugin System**: Integrated Rollup plugins for Babel, TypeScript, PostCSS, Terser, and more
71
- **Multi-Format Output**: Automatic generation of CommonJS, ESM, UMD, and modern JavaScript bundles
72
- **Zero Configuration**: Smart defaults that work without configuration files
73

74
## Capabilities
75

76
### Programmatic API
77

78
Core bundling functionality for integrating microbundle into build scripts or other tools. Provides complete control over bundling options and returns detailed build results.
79

80
```javascript { .api }
81
/**
82
 * Bundle JavaScript modules with zero configuration
83
 * @param inputOptions - Configuration options for bundling
84
 * @returns Promise resolving to build results
85
 */
86
function microbundle(inputOptions: MicrobundleOptions): Promise<MicrobundleResult>;
87

88
interface MicrobundleOptions {
89
  /** Entry module paths (default: auto-detected from package.json source field) */
90
  entries?: string[];
91
  /** Output formats: 'modern', 'esm', 'cjs', 'umd', 'iife' (default: 'modern,esm,cjs,umd') */
92
  format?: string;
93
  /** Alternative property name for format */
94
  formats?: string;
95
  /** Output directory or file path (default: from package.json main/module fields) */
96
  output?: string;
97
  /** Enable watch mode for development (default: false) */
98
  watch?: boolean;
99
  /** Target environment: 'web' or 'node' (default: 'web') */
100
  target?: "web" | "node";
101
  /** Enable/disable Terser compression (default: true for web, false for node) */
102
  compress?: boolean;
103
  /** Generate source maps: true, false, or 'inline' (default: true) */
104
  sourcemap?: boolean | string;
105
  /** Working directory (default: process.cwd()) */
106
  cwd?: string;
107
  /** External dependencies: 'none' or comma-separated module names */
108
  external?: string;
109
  /** Global variable mappings for UMD builds */
110
  globals?: string;
111
  /** Build-time constant definitions */
112
  define?: string;
113
  /** Module import aliases */
114
  alias?: string;
115
  /** Enforce strict mode */
116
  strict?: boolean;
117
  /** UMD global name */
118
  name?: string;
119
  /** Show raw byte sizes */
120
  raw?: boolean;
121
  /** JSX pragma function */
122
  jsx?: string;
123
  /** JSX fragment pragma */
124
  jsxFragment?: string;
125
  /** JSX import source */
126
  jsxImportSource?: string;
127
  /** TypeScript config file path */
128
  tsconfig?: string;
129
  /** Generate TypeScript declarations */
130
  generateTypes?: boolean;
131
  /** CSS output mode */
132
  css?: string;
133
  /** CSS modules configuration */
134
  "css-modules"?: string;
135
  /** Bundle web workers */
136
  workers?: boolean;
137
  /** Generate bundle visualization */
138
  visualize?: boolean;
139
  /** Use package.json main entries */
140
  "pkg-main"?: boolean;
141
  /** Watch mode callbacks */
142
  onStart?: (event: any) => void;
143
  onBuild?: (event: any) => void;
144
  onError?: (event: any) => void;
145
}
146

147
interface MicrobundleResult {
148
  /** Build output message with file sizes */
149
  output: string;
150
  /** Watch mode file watchers (when watch: true) */
151
  watchers?: Record<string, any>;
152
}
153
```
154

155
[Programmatic API](./programmatic-api.md)
156

157
### CLI Interface
158

159
Command-line interface providing build and watch commands with extensive configuration options. Designed for package.json scripts and terminal usage.
160

161
```bash { .api }
162
# Build command (default)
163
microbundle [entries...] --format esm,cjs,umd --output dist
164

165
# Watch command for development
166
microbundle watch [entries...] --sourcemap
167

168
# Common options
169
--target web|node        # Target environment
170
--compress               # Enable/disable compression  
171
--external dependencies  # Mark dependencies as external
172
--name GlobalName        # UMD global name
173
--tsconfig path         # Custom TypeScript config
174
```
175

176
[CLI Interface](./cli-interface.md)
177

178
## Output Formats
179

180
Microbundle generates multiple optimized bundle formats:
181

182
- **modern**: Modern JavaScript bundle for browsers supporting ES modules (smaller, faster)
183
- **esm**: Standard ECMAScript modules with broad compatibility
184
- **cjs**: CommonJS format for Node.js environments
185
- **umd**: Universal Module Definition for browser globals and AMD
186
- **iife**: Immediately Invoked Function Expression for direct browser usage
187

188
## TypeScript Support
189

190
Built-in TypeScript support with zero configuration:
191

192
- Automatic `.d.ts` declaration file generation
193
- Works with or without `tsconfig.json`
194
- Mixed JavaScript and TypeScript codebases supported
195
- Custom TypeScript configuration via `--tsconfig` option
196

197
## Types
198

199
```typescript { .api }
200
interface MicrobundleResult {
201
  /** Build output message with file information */
202
  output: string;
203
  /** File watchers for watch mode */
204
  watchers?: Record<string, any>;
205
}
206

207
// Utility types for advanced usage
208
type OutputFormat = "modern" | "esm" | "cjs" | "umd" | "iife";
209
type TargetEnvironment = "web" | "node";
210
type SourceMapOption = boolean | "inline";
211
type CSSOutputMode = "inline" | "external";
212
```