0
# Workspace Generation
1

2
Programmatic APIs for creating new workspaces in Turborepo monorepos, supporting both empty workspace creation and copying from existing templates.
3

4
## Capabilities
5

6
### Workspace Function
7

8
Main function for creating new workspaces programmatically.
9

10
```typescript { .api }
11
/**
12
 * Create a new workspace in the Turborepo monorepo
13
 * @param opts - Workspace generation options
14
 * @returns Promise that resolves when workspace is created
15
 */
16
function workspace(opts: TurboGeneratorCLIOptions): Promise<void>;
17

18
interface TurboGeneratorCLIOptions {
19
  /** Name for the new workspace */
20
  name?: string;
21
  /** Generate empty workspace (default: true) */
22
  empty: boolean;
23
  /** Generate using existing workspace as template */
24
  copy?: string | boolean;
25
  /** Where the new workspace should be created */
26
  destination?: string;
27
  /** Workspace type */
28
  type?: WorkspaceType;
29
  /** Repository root directory */
30
  root?: string;
31
  /** Path to example for GitHub URLs */
32
  examplePath?: string;
33
  /** Don't filter dependencies by workspace type */
34
  showAllDependencies: boolean;
35
}
36

37
type WorkspaceType = "app" | "package";
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { workspace } from "@turbo/gen/dist/commands";
44

45
// Create empty package
46
await workspace({
47
  name: "my-package",
48
  type: "package",
49
  empty: true,
50
  showAllDependencies: false
51
});
52

53
// Copy existing workspace
54
await workspace({
55
  name: "new-app",
56
  type: "app",
57
  empty: false,
58
  copy: "existing-app",
59
  showAllDependencies: false
60
});
61

62
// Create with custom destination
63
await workspace({
64
  name: "shared-ui",
65
  type: "package",
66
  empty: true,
67
  destination: "packages/ui",
68
  showAllDependencies: false
69
});
70
```
71

72
### Generator Functions
73

74
Low-level generator functions for different workspace creation methods.
75

76
#### Empty Generator
77

78
```typescript { .api }
79
/**
80
 * Generate an empty workspace
81
 * @param args - Generator arguments with project and options
82
 * @returns Promise that resolves when generation is complete
83
 */
84
function generate(args: TurboGeneratorArguments): Promise<void>;
85

86
interface TurboGeneratorArguments {
87
  project: Project;
88
  opts: TurboGeneratorOptions;
89
}
90

91
type TurboGeneratorOptions = Omit<TurboGeneratorCLIOptions, "copy" | "empty"> & {
92
  copy: CopyData;
93
  method: "copy" | "empty";
94
};
95
```
96

97
#### Copy Generator
98

99
```typescript { .api }
100
/**
101
 * Generate workspace by copying from existing template
102
 * @param args - Generator arguments with project and options
103
 * @returns Promise that resolves when generation is complete
104
 */
105
function generate(args: TurboGeneratorArguments): Promise<void>;
106

107
interface CopyData {
108
  type: "internal" | "external";
109
  source: string;
110
}
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
import { generate as emptyGenerate } from "@turbo/gen/dist/generators/empty";
117
import { generate as copyGenerate } from "@turbo/gen/dist/generators/copy";
118
import { getProject } from "@turbo/gen/dist/utils/getProject";
119

120
// Generate empty workspace
121
const project = await getProject({ root: process.cwd() });
122
await emptyGenerate({
123
  project,
124
  opts: {
125
    name: "my-package",
126
    type: "package",
127
    method: "empty",
128
    copy: { type: "internal", source: "" },
129
    showAllDependencies: false
130
  }
131
});
132

133
// Copy workspace
134
await copyGenerate({
135
  project,
136
  opts: {
137
    name: "new-app",
138
    type: "app", 
139
    method: "copy",
140
    copy: { type: "internal", source: "existing-app" },
141
    showAllDependencies: false
142
  }
143
});
144
```
145

146
### Workspace Requirements Gathering
147

148
Utility for collecting all requirements needed for workspace creation.
149

150
```typescript { .api }
151
/**
152
 * Gather all requirements for workspace creation including prompts
153
 * @param args - Generator arguments
154
 * @returns Promise with collected workspace requirements
155
 */
156
function gatherAddRequirements(args: TurboGeneratorArguments): Promise<{
157
  type: WorkspaceType;
158
  name: string;
159
  location: { absolute: string; relative: string };
160
  source: Workspace | undefined;
161
  dependencies: DependencyGroups;
162
}>;
163

164
interface DependencyGroups {
165
  dependencies: string[];
166
  devDependencies: string[];
167
  peerDependencies: string[];
168
}
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
import { gatherAddRequirements } from "@turbo/gen/dist/utils/gatherAddRequirements";
175

176
const requirements = await gatherAddRequirements({
177
  project,
178
  opts: {
179
    name: "my-package",
180
    type: "package",
181
    method: "empty",
182
    copy: { type: "internal", source: "" },
183
    showAllDependencies: false
184
  }
185
});
186

187
console.log(requirements.name); // "my-package"
188
console.log(requirements.location.relative); // "packages/my-package"
189
console.log(requirements.dependencies); // ["react", "typescript"]
190
```
191

192
## Workspace Utilities
193

194
### Workspace Listing
195

196
Get filtered lists of available workspaces.
197

198
```typescript { .api }
199
/**
200
 * Get filtered list of workspaces for selection
201
 * @param args - Project and filtering options
202
 * @returns Array of workspaces or separators for UI
203
 */
204
function getWorkspaceList(args: {
205
  project: Project;
206
  type: WorkspaceType;
207
  showAllDependencies?: boolean;
208
}): Array<Workspace | Separator>;
209
```
210

211
### Workspace Structure Analysis
212

213
Analyze the structure of workspaces in the monorepo.
214

215
```typescript { .api }
216
/**
217
 * Analyze workspace structure in the monorepo
218
 * @param args - Project instance
219
 * @returns Workspace structure information
220
 */
221
function getWorkspaceStructure(args: {
222
  project: Project;
223
}): WorkspaceStructure;
224

225
interface WorkspaceStructure {
226
  hasRootApps: boolean;
227
  hasRootPackages: boolean;
228
  workspacesByGroup: Record<string, Array<Workspace>>;
229
  nonAppWorkspaces: Array<Workspace>;
230
}
231

232
/**
233
 * Get group name for a workspace based on its location
234
 * @param args - Project and workspace
235
 * @returns Group name for the workspace
236
 */
237
function getGroupFromWorkspace(args: {
238
  project: Project;
239
  workspace: Workspace;
240
}): string;
241
```
242

243
### Workspace Roots
244

245
Get available workspace root directories.
246

247
```typescript { .api }
248
/**
249
 * Get workspace root directories from project configuration
250
 * @param args - Project instance
251
 * @returns Array of workspace root directory paths
252
 */
253
function getWorkspaceRoots(args: {
254
  project: Project;
255
}): Array<string>;
256
```
257

258
**Usage Examples:**
259

260
```typescript
261
import { 
262
  getWorkspaceList, 
263
  getWorkspaceStructure, 
264
  getWorkspaceRoots 
265
} from "@turbo/gen/dist/utils";
266

267
// Get available workspaces for copying
268
const workspaces = getWorkspaceList({
269
  project,
270
  type: "package",
271
  showAllDependencies: false
272
});
273

274
// Analyze workspace structure
275
const structure = getWorkspaceStructure({ project });
276
console.log(structure.hasRootApps); // true/false
277
console.log(structure.workspacesByGroup); // { "apps": [...], "packages": [...] }
278

279
// Get workspace roots
280
const roots = getWorkspaceRoots({ project });
281
console.log(roots); // ["apps", "packages", "tools"]
282
```
283

284
## Interactive Prompts
285

286
Programmatic access to the same prompts used by the CLI.
287

288
### Name Prompt
289

290
```typescript { .api }
291
/**
292
 * Prompt for workspace name with validation
293
 * @param args - Prompt configuration
294
 * @returns Promise with user's answer
295
 */
296
function name(args: {
297
  override?: string;
298
  suggestion?: string;
299
  workspaceType: WorkspaceType;
300
}): Promise<{ answer: string }>;
301
```
302

303
### Type Prompt
304

305
```typescript { .api }
306
/**
307
 * Prompt for workspace type selection
308
 * @param args - Prompt configuration
309
 * @returns Promise with selected workspace type
310
 */
311
function type(args: {
312
  override?: WorkspaceType;
313
  message?: string;
314
}): Promise<{ answer: WorkspaceType }>;
315
```
316

317
### Location Prompt
318

319
```typescript { .api }
320
/**
321
 * Determine workspace location with user input
322
 * @param args - Location prompt configuration
323
 * @returns Promise with absolute and relative paths
324
 */
325
function location(args: {
326
  workspaceType: WorkspaceType;
327
  workspaceName: string;
328
  destination?: string;
329
  project: Project;
330
}): Promise<{ absolute: string; relative: string }>;
331
```
332

333
### Source Prompt
334

335
```typescript { .api }
336
/**
337
 * Prompt for source workspace selection when copying
338
 * @param args - Source selection configuration
339
 * @returns Promise with selected workspace
340
 */
341
function source(args: {
342
  override?: string;
343
  workspaces: Array<Workspace | Separator>;
344
  workspaceName: string;
345
}): Promise<{ answer: Workspace }>;
346
```
347

348
### Dependencies Prompt
349

350
```typescript { .api }
351
/**
352
 * Prompt for dependency selection
353
 * @param args - Dependency prompt configuration
354
 * @returns Promise with selected dependency groups
355
 */
356
function dependencies(args: {
357
  workspaceName: string;
358
  project: Project;
359
  workspaceSource?: Workspace;
360
  showAllDependencies?: boolean;
361
}): Promise<DependencyGroups>;
362
```
363

364
**Usage Examples:**
365

366
```typescript
367
import { 
368
  name, 
369
  type, 
370
  location, 
371
  dependencies 
372
} from "@turbo/gen/dist/commands/workspace/prompts";
373

374
// Get workspace name
375
const nameResult = await name({
376
  workspaceType: "package",
377
  suggestion: "my-package"
378
});
379

380
// Get workspace type
381
const typeResult = await type({
382
  message: "What type of workspace would you like to create?"
383
});
384

385
// Get location
386
const locationResult = await location({
387
  workspaceType: "package",
388
  workspaceName: "my-package",
389
  project
390
});
391

392
// Get dependencies
393
const deps = await dependencies({
394
  workspaceName: "my-package",
395
  project,
396
  showAllDependencies: false
397
});
398
```