0
# SWC Bundler (spack)
1
2
Bundling functionality that uses SWC's high-performance bundler to create optimized JavaScript bundles from TypeScript and JavaScript sources.
3
4
## Capabilities
5
6
### Spack CLI Command
7
8
The SWC bundler command for creating optimized JavaScript bundles.
9
10
```bash { .api }
11
npx spack [options]
12
13
# Key Options:
14
--config [path] # Path to spack.config.js file
15
--mode <development|production|none> # Build mode
16
--target [browser|node] # Target runtime environment
17
--context [path] # Base directory for resolving entry
18
--entry [list] # List of entry points
19
-o --output # Output path and file for assets
20
--output-path # Output directory as absolute path
21
--debug # Switch loaders to debug mode
22
```
23
24
**Configuration File (spack.config.js):**
25
26
```javascript
27
module.exports = {
28
entry: {
29
main: "./src/index.ts",
30
},
31
output: {
32
path: "./dist",
33
name: "[name].js",
34
},
35
mode: "production",
36
target: "browser",
37
module: {
38
rules: [
39
{
40
test: /\.ts$/,
41
use: {
42
loader: "swc-loader",
43
options: {
44
jsc: {
45
parser: {
46
syntax: "typescript",
47
},
48
},
49
},
50
},
51
},
52
],
53
},
54
};
55
```
56
57
**Usage Examples:**
58
59
```bash
60
# Basic bundling with config file
61
npx spack --config spack.config.js
62
63
# Specify entry and output
64
npx spack --entry ./src/index.ts --output dist/bundle.js
65
66
# Development mode with browser target
67
npx spack --mode development --target browser
68
69
# Multiple entries
70
npx spack --entry ./src/main.ts,./src/worker.ts --output-path dist
71
```
72
73
### Programmatic API
74
75
Direct access to spack bundling functionality through @swc/core.
76
77
```typescript { .api }
78
/**
79
* Parse spack CLI arguments into configuration options
80
* @param args - Command-line arguments array
81
* @returns Promise resolving to parsed CLI and bundle options
82
*/
83
function parseSpackArgs(args: string[]): Promise<{
84
cliOptions: SpackCliOptions;
85
spackOptions: BundleOptions;
86
}>;
87
88
interface SpackCliOptions {
89
/** Enable debug mode for loaders */
90
debug: boolean;
91
}
92
93
// BundleOptions is re-exported from @swc/core/spack
94
type BundleOptions = import("@swc/core/spack").BundleOptions;
95
```
96
97
**Usage Example:**
98
99
```typescript
100
import { bundle } from "@swc/core";
101
import { parseSpackArgs } from "@swc/cli/spack";
102
103
// Parse CLI arguments
104
const { spackOptions, cliOptions } = await parseSpackArgs(process.argv);
105
106
// Perform bundling
107
const output = await bundle(spackOptions);
108
109
// Process output
110
for (const [name, result] of Object.entries(output)) {
111
console.log(`Bundle ${name}: ${result.code.length} bytes`);
112
if (result.map) {
113
console.log(`Source map: ${result.map.length} bytes`);
114
}
115
}
116
```
117
118
### Bundle Configuration
119
120
Spack uses configuration files similar to webpack but optimized for SWC's bundling capabilities.
121
122
```typescript { .api }
123
interface BundleOptions {
124
/** Entry points for bundling */
125
entry: string | string[] | Record<string, string>;
126
/** Output configuration */
127
output?: {
128
/** Output directory path */
129
path: string;
130
/** Output filename pattern */
131
name: string;
132
};
133
/** Build mode */
134
mode?: "development" | "production" | "none";
135
/** Target runtime environment */
136
target?: "browser" | "node";
137
/** Base directory for resolving entry points */
138
context?: string;
139
/** Module processing configuration */
140
module?: {
141
rules: Array<{
142
test: RegExp;
143
use: {
144
loader: string;
145
options?: any;
146
};
147
}>;
148
};
149
}
150
```
151
152
### Bundle Execution
153
154
The main bundling process that processes files and generates optimized output.
155
156
```typescript { .api }
157
/**
158
* Execute the bundling process
159
* @returns Promise that resolves when bundling completes
160
*/
161
async function build(): Promise<void>;
162
163
/**
164
* Check if an entry name is user-defined
165
* @param name - Entry name to check
166
* @returns True if entry is user-defined
167
*/
168
function isUserDefinedEntry(name: string): boolean;
169
```
170
171
**Bundle Process:**
172
173
1. Parse spack configuration and CLI options
174
2. Resolve entry points and dependencies
175
3. Apply module transformations using SWC
176
4. Generate optimized bundles with code splitting
177
5. Write output files with optional source maps
178
6. Report bundling performance metrics
179
180
**Output Structure:**
181
182
```typescript
183
// Bundle output format
184
type BundleOutput = Record<string, {
185
code: string; // Generated JavaScript code
186
map?: string; // Optional source map
187
}>;
188
```
189
190
### Performance Features
191
192
Spack leverages SWC's Rust-based architecture for high-performance bundling:
193
194
- **Fast Compilation**: Native Rust performance for TypeScript/JavaScript transformation
195
- **Parallel Processing**: Multi-threaded bundling for large codebases
196
- **Tree Shaking**: Dead code elimination for smaller bundles
197
- **Code Splitting**: Automatic chunk generation for optimal loading
198
- **Source Maps**: Full source map support for debugging
199
- **Watch Mode**: Fast incremental rebuilds (planned feature)
200
201
### Integration Examples
202
203
```bash
204
# Package.json scripts
205
{
206
"scripts": {
207
"build": "spack --config spack.config.js",
208
"build:dev": "spack --mode development --debug",
209
"build:prod": "spack --mode production --target browser"
210
}
211
}
212
213
# CI/CD integration
214
npx spack --mode production --output-path dist/
215
```
216
217
## Types
218
219
```typescript { .api }
220
// Re-exported from @swc/core/spack
221
type BundleOptions = import("@swc/core/spack").BundleOptions;
222
type CompileBundleOptions = import("@swc/core/spack").compileBundleOptions;
223
224
interface SpackCliOptions {
225
debug: boolean;
226
}
227
```