0
# Core Generator System
1

2
The foundational Generator class and lifecycle management system that orchestrates the entire scaffolding process through predefined execution queues.
3

4
## Capabilities
5

6
### Generator Class
7

8
The main Generator class that extends BaseGenerator with simple-git integration.
9

10
```typescript { .api }
11
/**
12
 * Main Generator class that provides the complete API for building scaffolding tools
13
 */
14
export default class Generator<
15
  O extends BaseOptions = BaseOptions,
16
  F extends BaseFeatures = BaseFeatures
17
> extends BaseGenerator<O, F> {
18
  constructor(options: O, features?: F);
19
  constructor(args: string[], options: O, features?: F);
20
  
21
  // Core properties
22
  readonly options: O;
23
  readonly env: Environment;
24
  readonly fs: MemFsEditor;
25
  readonly log: Logger;
26
  readonly args: string[];
27
  readonly appname: string;
28
  readonly config: Storage;
29
  readonly packageJson: Storage;
30
  readonly yoGeneratorVersion: string;
31
  readonly _destinationRoot: string;
32
  readonly _sourceRoot: string;
33
  
34
  // Git integration (specific to main Generator class)
35
  readonly simpleGit: SimpleGit;
36
}
37
```
38

39
**Usage Example:**
40

41
```typescript
42
import Generator from "yeoman-generator";
43

44
export default class MyGenerator extends Generator {
45
  constructor(args, opts) {
46
    super(args, opts);
47
    
48
    // Access generator properties
49
    console.log(this.appname); // Determined app name
50
    console.log(this.yoGeneratorVersion); // Generator version
51
    console.log(this.destinationRoot()); // Current destination
52
  }
53
}
54
```
55

56
### BaseGenerator Class
57

58
The foundational generator class providing the complete API surface.
59

60
```typescript { .api }
61
/**
62
 * Base generator class that provides the complete scaffolding API
63
 */
64
class BaseGenerator<O extends BaseOptions = BaseOptions, F extends BaseFeatures = BaseFeatures> 
65
  extends EventEmitter {
66
  
67
  constructor(options: O, features?: F);
68
  constructor(args: string[], options: O, features?: F);
69
  
70
  // Core properties
71
  readonly options: O;
72
  readonly _initOptions: O;
73
  readonly _args: string[];
74
  readonly _namespace: string;
75
  readonly resolved: string;
76
  description: string;
77
  readonly env: Environment;
78
  readonly fs: MemFsEditor;
79
  readonly log: Logger;
80
  readonly args: string[];
81
  readonly appname: string;
82
  readonly yoGeneratorVersion: string;
83
  
84
  // Configuration storage
85
  readonly config: Storage;
86
  readonly packageJson: Storage;
87
  generatorConfig?: Storage;
88
  instanceConfig?: Storage;
89
  
90
  // Core methods
91
  run(): Promise<void>;
92
  debug(formatter: any, ...args: any[]): void;
93
  setFeatures(features: F): void;
94
  getFeatures(): F;
95
  checkEnvironmentVersion(version: string, warning?: boolean): boolean | undefined;
96
  rootGeneratorName(): string;
97
  rootGeneratorVersion(): string;
98
  createStorage(storePath: string, options?: string | StorageOptions): Storage;
99
}
100
```
101

102
### Lifecycle Queues
103

104
The predefined execution order for generator methods.
105

106
```typescript { .api }
107
/**
108
 * Static queue names that define the execution order of generator methods
109
 */
110
static readonly queues: readonly [
111
  'initializing',
112
  'prompting', 
113
  'configuring',
114
  'default',
115
  'writing',
116
  'transform',
117
  'conflicts',
118
  'install',
119
  'end'
120
];
121
```
122

123
**Usage Example:**
124

125
```typescript
126
export default class MyGenerator extends Generator {
127
  // Methods named after queues run in predefined order
128
  initializing() {
129
    // Setup and initialization
130
    this.log('Initializing generator...');
131
  }
132
  
133
  async prompting() {
134
    // User prompts
135
    this.answers = await this.prompt([...]);
136
  }
137
  
138
  configuring() {
139
    // Save configurations
140
    this.config.set('answers', this.answers);
141
  }
142
  
143
  writing() {
144
    // Write files
145
    this.renderTemplate('template.ejs', 'output.js', this.answers);
146
  }
147
  
148
  install() {
149
    // Install dependencies
150
    this.spawnCommand('npm', ['install']);
151
  }
152
  
153
  end() {
154
    // Final cleanup and messages
155
    this.log('Generator complete!');
156
  }
157
}
158
```
159

160
### Path Management
161

162
Methods for managing source templates and destination paths.
163

164
```typescript { .api }
165
/**
166
 * Get or set the generator destination root directory
167
 * @param rootPath - New destination root path
168
 * @returns Current destination root path
169
 */
170
destinationRoot(rootPath?: string): string;
171

172
/**
173
 * Get or set the generator source root directory  
174
 * @param rootPath - New source root path
175
 * @returns Current source root path
176
 */
177
sourceRoot(rootPath?: string): string;
178

179
/**
180
 * Join paths to the destination root
181
 * @param dest - Path parts to join
182
 * @returns Joined path to destination
183
 */
184
destinationPath(...dest: string[]): string;
185

186
/**
187
 * Join paths to the source root (template path)
188
 * @param dest - Path parts to join
189
 * @returns Joined path to template
190
 */
191
templatePath(...dest: string[]): string;
192
```
193

194
**Usage Example:**
195

196
```typescript
197
export default class MyGenerator extends Generator {
198
  constructor(args, opts) {
199
    super(args, opts);
200
    
201
    // Set custom template location
202
    this.sourceRoot(path.join(__dirname, 'templates'));
203
  }
204
  
205
  writing() {
206
    // Use path helpers
207
    const templateFile = this.templatePath('app', 'index.js');
208
    const outputFile = this.destinationPath('src', 'index.js');
209
    
210
    this.fs.copy(templateFile, outputFile);
211
  }
212
}
213
```
214

215
### App Name Determination
216

217
Automatically determine the application name from package.json or directory.
218

219
```typescript { .api }
220
/**
221
 * Determines the name of the application
222
 * First checks for name in package.json, then defaults to directory name
223
 * @returns The determined application name
224
 */
225
determineAppname(): string;
226
```
227

228
### Generator Metadata
229

230
Methods for accessing generator information.
231

232
```typescript { .api }
233
/**
234
 * Determine the root generator name (the one extending Generator)
235
 * @returns The name of the root generator
236
 */
237
rootGeneratorName(): string;
238

239
/**
240
 * Determine the root generator version (the one extending Generator)  
241
 * @returns The version of the root generator
242
 */
243
rootGeneratorVersion(): string;
244
```
245

246
### Environment Version Checking
247

248
Validate that the yeoman-environment version meets requirements.
249

250
```typescript { .api }
251
/**
252
 * Check that the environment version meets minimum requirements
253
 * @param version - Required version string
254
 * @param warning - Whether to show warning instead of throwing error
255
 * @returns Whether version check passed
256
 */
257
checkEnvironmentVersion(version: string, warning?: boolean): boolean | undefined;
258
checkEnvironmentVersion(packageDependency: string, version: string, warning?: boolean): boolean | undefined;
259
```
260

261
### Feature Configuration
262

263
Configure generator behaviors and capabilities.
264

265
```typescript { .api }
266
/**
267
 * Configure Generator behaviors
268
 * @param features - Feature configuration object
269
 */
270
setFeatures(features: F): void;
271

272
/**
273
 * Get current feature configuration
274
 * @returns Current features
275
 */
276
getFeatures(): F;
277
```
278

279
**Usage Example:**
280

281
```typescript
282
export default class MyGenerator extends Generator {
283
  constructor(args, opts) {
284
    super(args, opts);
285
    
286
    // Configure generator features
287
    this.setFeatures({
288
      unique: 'namespace', // Only one instance per namespace
289
      customPriorities: [
290
        { priorityName: 'setup', before: 'prompting' }
291
      ]
292
    });
293
  }
294
}
295
```
296

297
## Types
298

299
```typescript { .api }
300
interface BaseOptions {
301
  destinationRoot?: string;
302
  skipInstall?: boolean;
303
  skipCheckEnv?: boolean;
304
  ignoreVersionCheck?: boolean;
305
  askAnswered?: boolean;
306
  localConfigOnly?: boolean;
307
  skipCache?: boolean;
308
  skipLocalCache?: boolean;
309
  description?: string;
310
  skipParseOptions?: boolean;
311
  customPriorities?: Priority[];
312
}
313

314
interface BaseFeatures {
315
  uniqueBy?: string;
316
  unique?: true | 'argument' | 'namespace';
317
  tasksMatchingPriority?: boolean;
318
  taskPrefix?: string;
319
  customInstallTask?: boolean | ((...args: any[]) => void | Promise<void>);
320
  customCommitTask?: boolean | ((...args: any[]) => void | Promise<void>);
321
  skipParseOptions?: boolean;
322
  customPriorities?: Priority[];
323
  inheritTasks?: boolean;
324
}
325
```