0
# Workspace Support
1

2
Multi-package support for monorepos with filtering and configuration management. Enables building multiple packages in a single command with shared configuration and efficient dependency management.
3

4
## Capabilities
5

6
### Workspace Configuration
7

8
Interface for configuring workspace behavior in monorepos and multi-package projects.
9

10
```typescript { .api }
11
interface Workspace {
12
  /**
13
   * Workspace directories. Glob patterns are supported.
14
   * - `auto`: Automatically detect `package.json` files in the workspace.
15
   * @default 'auto'
16
   */
17
  include?: Arrayable<string> | 'auto';
18
  
19
  /**
20
   * Exclude directories from workspace.
21
   * Defaults to all `node_modules`, `dist`, `test`, `tests`, `temp`, and `tmp` directories.
22
   */
23
  exclude?: Arrayable<string>;
24
  
25
  /**
26
   * Path to the workspace configuration file.
27
   */
28
  config?: boolean | string;
29
}
30
```
31

32
### Workspace Options
33

34
Main workspace configuration options in the build configuration.
35

36
```typescript { .api }
37
interface Options {
38
  /**
39
   * Enable workspace mode for building multiple packages in a monorepo
40
   */
41
  workspace?: Workspace | Arrayable<string> | true;
42
  
43
  /**
44
   * Filter workspace packages. Only available in workspace mode.
45
   */
46
  filter?: RegExp | string | string[];
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { defineConfig } from "tsdown";
54

55
// Enable workspace mode with auto-discovery
56
export default defineConfig({
57
  workspace: true,
58
  format: ["esm", "cjs"],
59
  dts: true
60
});
61

62
// Workspace with custom include patterns
63
export default defineConfig({
64
  workspace: {
65
    include: ["packages/*", "apps/*"],
66
    exclude: ["packages/*/test"]
67
  },
68
  format: "esm"
69
});
70

71
// Workspace with string shorthand
72
export default defineConfig({
73
  workspace: ["packages/*", "tools/*"],
74
  sourcemap: true
75
});
76

77
// Workspace with filtering
78
export default defineConfig({
79
  workspace: true,
80
  filter: /^@myorg\/.*$/, // Only packages matching pattern
81
  format: ["esm", "cjs"]
82
});
83
```
84

85
### Default Exclusions
86

87
Workspace discovery automatically excludes common directories that shouldn't be treated as packages:
88

89
- `**/node_modules/**`
90
- `**/dist/**`
91
- `**/test?(s)/**`
92
- `**/t?(e)mp/**`
93

94
### CLI Workspace Commands
95

96
Command-line interface for workspace operations.
97

98
```bash
99
# Enable workspace mode
100
tsdown --workspace
101

102
# Workspace with custom directory
103
tsdown --workspace packages
104

105
# Filter workspace packages
106
tsdown --workspace --filter @myorg
107
tsdown --workspace --filter "/ui-.*/"
108

109
# Multiple filters
110
tsdown --workspace --filter "ui,utils"
111
```
112

113
### Package Discovery
114

115
Workspace package discovery process:
116

117
1. **Auto Discovery**: Searches for `package.json` files in workspace directories
118
2. **Pattern Matching**: Uses glob patterns to find package directories
119
3. **Exclusion Filtering**: Applies exclude patterns to remove unwanted directories
120
4. **Filter Application**: Applies user-defined filters to discovered packages
121
5. **Configuration Loading**: Loads individual package configurations
122

123
**Discovery Examples:**
124

125
```typescript
126
// Auto-discovery (default)
127
{
128
  workspace: {
129
    include: 'auto' // Finds all package.json files
130
  }
131
}
132

133
// Explicit patterns
134
{
135
  workspace: {
136
    include: [
137
      "packages/*",      // All direct subdirectories in packages/
138
      "apps/*/lib",      // Nested lib directories in apps/
139
      "tools/build-*"    // Build tools matching pattern
140
    ]
141
  }
142
}
143

144
// With exclusions
145
{
146
  workspace: {
147
    include: "packages/*",
148
    exclude: [
149
      "packages/*/test",
150
      "packages/*/docs",
151
      "packages/legacy-*"
152
    ]
153
  }
154
}
155
```
156

157
### Filtering Packages
158

159
Multiple filtering options for targeting specific packages in the workspace.
160

161
```typescript { .api }
162
/**
163
 * Filter patterns for workspace packages
164
 */
165
type FilterPattern = RegExp | string | string[];
166
```
167

168
**Filter Types:**
169

170
1. **String Matching**: Substring matching against package paths
171
2. **Regular Expression**: Pattern matching with full regex support
172
3. **Array of Patterns**: Multiple filters applied with OR logic
173

174
**Filter Examples:**
175

176
```typescript
177
// String filter - matches paths containing "ui"
178
export default defineConfig({
179
  workspace: true,
180
  filter: "ui"
181
});
182

183
// Regex filter - matches packages starting with @myorg/
184
export default defineConfig({
185
  workspace: true,
186
  filter: /^@myorg\/.*/
187
});
188

189
// Multiple filters - matches any of the patterns
190
export default defineConfig({
191
  workspace: true,
192
  filter: ["ui", "utils", "shared"]
193
});
194

195
// Complex regex - matches UI and utility packages
196
export default defineConfig({
197
  workspace: true,
198
  filter: /\/(ui-|utils-|shared-)/
199
});
200
```
201

202
### Configuration Inheritance
203

204
Workspace packages inherit configuration from the root with package-specific overrides.
205

206
**Root Configuration (`tsdown.config.ts`):**
207

208
```typescript
209
export default defineConfig({
210
  workspace: true,
211
  format: ["esm", "cjs"],
212
  dts: true,
213
  sourcemap: true,
214
  clean: true
215
});
216
```
217

218
**Package-Specific Configuration (`packages/ui-lib/tsdown.config.ts`):**
219

220
```typescript
221
export default defineConfig({
222
  // Inherits: format, dts, sourcemap, clean from root
223
  entry: "src/index.ts",
224
  external: ["react", "react-dom"], // Package-specific externals
225
  target: "es2020" // Override root target
226
});
227
```
228

229
### Workspace Configuration Files
230

231
Each workspace package can have its own configuration file for package-specific settings.
232

233
```typescript { .api }
234
interface Workspace {
235
  /**
236
   * Path to workspace configuration file
237
   * - `true`: Use default tsdown.config.* files
238
   * - `string`: Use specific configuration file path
239
   * - `false`: Disable workspace configuration files
240
   */
241
  config?: boolean | string;
242
}
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
// Use default config files in each package
249
{
250
  workspace: {
251
    include: "packages/*",
252
    config: true
253
  }
254
}
255

256
// Use specific config file name
257
{
258
  workspace: {
259
    include: "packages/*", 
260
    config: "build.config.ts"
261
  }
262
}
263

264
// Disable package-specific configs (root config only)
265
{
266
  workspace: {
267
    include: "packages/*",
268
    config: false
269
  }
270
}
271
```
272

273
### Build Execution
274

275
Workspace builds execute in the following sequence:
276

277
1. **Root Configuration**: Load and resolve root configuration
278
2. **Package Discovery**: Find all packages matching workspace criteria
279
3. **Filter Application**: Apply filters to reduce package set
280
4. **Configuration Resolution**: Resolve configuration for each package
281
5. **Parallel Builds**: Execute builds for all packages in parallel
282
6. **Error Handling**: Collect and report errors from all packages
283

284
### Example Workspace Structures
285

286
**Typical Monorepo Structure:**
287

288
```
289
my-monorepo/
290
├── packages/
291
│   ├── ui-lib/
292
│   │   ├── src/index.ts
293
│   │   ├── package.json
294
│   │   └── tsdown.config.ts
295
│   ├── utils/
296
│   │   ├── src/index.ts
297
│   │   ├── package.json
298
│   │   └── tsdown.config.ts
299
│   └── cli-tool/
300
│       ├── src/index.ts
301
│       ├── package.json
302
│       └── tsdown.config.ts
303
├── apps/
304
│   └── web-app/
305
│       ├── package.json
306
│       └── (not built with tsdown)
307
├── tsdown.config.ts (root config)
308
└── package.json
309
```
310

311
**Configuration for Above Structure:**
312

313
```typescript
314
// Root tsdown.config.ts
315
export default defineConfig({
316
  workspace: {
317
    include: "packages/*", // Only build packages/, not apps/
318
    exclude: ["packages/*/test"]
319
  },
320
  format: ["esm", "cjs"],
321
  dts: true,
322
  clean: true
323
});
324
```
325

326
### Error Handling
327

328
Workspace builds handle errors gracefully:
329

330
- **Individual Package Errors**: Reported with package context
331
- **Configuration Errors**: Validation errors shown with package path
332
- **Build Failures**: Continue building other packages, report all failures
333
- **Filter Errors**: No packages matching filters results in error
334
- **Discovery Errors**: Missing packages or invalid patterns reported clearly