0
# Turbo Gen
1

2
Turbo Gen is a code generation tool for Turborepo monorepos that provides utilities for creating workspaces and running custom generators. It offers both a CLI interface and programmatic APIs for extending Turborepo projects with scaffolding capabilities.
3

4
## Package Information
5

6
- **Package Name**: @turbo/gen
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @turbo/gen`
10

11
## Core Imports
12

13
```typescript
14
import type { PlopTypes } from "@turbo/gen";
15
```
16

17
For programmatic use (accessing internal APIs):
18

19
```typescript
20
import { workspace, run, raw } from "@turbo/gen/dist/commands";
21
import { generate } from "@turbo/gen/dist/generators";
22
```
23

24
## Basic Usage
25

26
### CLI Usage
27

28
Most common usage is through the CLI:
29

30
```bash
31
# Run a custom generator
32
npx @turbo/gen run my-generator
33

34
# Create a new workspace
35
npx @turbo/gen workspace --name my-package --type package
36

37
# Copy existing workspace as template
38
npx @turbo/gen workspace --copy existing-package --name new-package
39
```
40

41
### Programmatic Usage
42

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

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

55
## Architecture
56

57
Turbo Gen is structured around several key components:
58

59
- **CLI Interface**: Commander.js-based CLI with three main commands (`run`, `workspace`, `raw`)
60
- **Generator System**: Built on node-plop for code generation with three built-in generators (custom, empty, copy)
61
- **Command Layer**: High-level command handlers that orchestrate generator execution
62
- **Utility Layer**: Core functionality for project management, workspace operations, and plop integration
63
- **Template System**: Built-in templates for TypeScript and JavaScript generator configurations
64

65
## Capabilities
66

67
### CLI Commands
68

69
Command-line interface for running generators and creating workspaces. Provides interactive prompts and validation for all operations.
70

71
```typescript { .api }
72
// CLI command signatures (accessed via npx @turbo/gen)
73
run [generator-name] --config <config> --root <dir> --args <args...>
74
workspace --name <name> --type <type> --empty|--copy [source] --destination <dir>
75
raw <type> --json <arguments>
76
```
77

78
[CLI Commands](./cli-commands.md)
79

80
### Workspace Generation
81

82
Programmatic APIs for creating new workspaces in Turborepo monorepos. Supports both empty workspace creation and copying from existing templates.
83

84
```typescript { .api }
85
interface TurboGeneratorCLIOptions {
86
  name?: string;
87
  empty: boolean;
88
  copy?: string | boolean;
89
  destination?: string;
90
  type?: WorkspaceType;
91
  root?: string;
92
  examplePath?: string;
93
  showAllDependencies: boolean;
94
}
95

96
function workspace(opts: TurboGeneratorCLIOptions): Promise<void>;
97
```
98

99
[Workspace Generation](./workspace-generation.md)
100

101
### Custom Generators
102

103
System for running custom plop-based generators with Turborepo integration. Supports both TypeScript and JavaScript generator configurations.
104

105
```typescript { .api }
106
interface CustomGeneratorCLIOptions {
107
  config?: string;
108
  root?: string;
109
  args?: Array<string>;
110
}
111

112
function run(generator: string | undefined, opts: CustomGeneratorCLIOptions): Promise<void>;
113
```
114

115
[Custom Generators](./custom-generators.md)
116

117
### Generator Utilities
118

119
Core utilities for generator development including plop integration, project management, and workspace operations.
120

121
```typescript { .api }
122
function getProject(args: { root?: string }): Promise<Project>;
123

124
function getPlop(args: {
125
  project: Project;
126
  configPath?: string;
127
}): NodePlopAPI | undefined;
128

129
function runCustomGenerator(args: {
130
  project: Project;
131
  generator: string;
132
  bypassArgs?: Array<string>;
133
  configPath?: string;
134
}): Promise<void>;
135
```
136

137
[Generator Utilities](./generator-utilities.md)
138

139
## Types
140

141
### Core Types
142

143
```typescript { .api }
144
// Re-exported from node-plop for generator configuration
145
export type { PlopTypes };
146

147
type WorkspaceType = "app" | "package";
148

149
interface CopyData {
150
  type: "internal" | "external";
151
  source: string;
152
}
153
```
154

155
### Generator Arguments
156

157
```typescript { .api }
158
interface TurboGeneratorArguments {
159
  project: Project;
160
  opts: TurboGeneratorOptions;
161
}
162

163
interface CustomGeneratorArguments {
164
  generator: string | undefined;
165
  project: Project;
166
  opts: CustomGeneratorCLIOptions;
167
}
168
```
169

170
### Error Types
171

172
```typescript { .api }
173
type GenerateErrorType =
174
  | "plop_error_running_generator"
175
  | "plop_unable_to_load_config"
176
  | "plop_generator_not_found"
177
  | "plop_no_config"
178
  | "config_directory_already_exists"
179
  | "unknown";
180

181
class GeneratorError extends Error {
182
  public type: GenerateErrorType;
183
  constructor(message: string, opts?: GeneratorErrorOptions);
184
}
185
```