0
# Yeoman Generator
1

2
Yeoman Generator is a Rails-inspired generator system that provides scaffolding for applications. It offers a comprehensive framework for building interactive command-line tools that can scaffold entire applications, copy boilerplate files, prompt users for preferences, and generate tailored project structures.
3

4
## Package Information
5

6
- **Package Name**: yeoman-generator
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install yeoman-generator`
10

11
## Core Imports
12

13
```typescript
14
import Generator from "yeoman-generator";
15
```
16

17
For ESM with typed import:
18

19
```typescript
20
import Generator, { type BaseOptions, type BaseFeatures, Storage } from "yeoman-generator";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const Generator = require("yeoman-generator");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import Generator from "yeoman-generator";
33

34
export default class MyGenerator extends Generator {
35
  // Define lifecycle methods
36
  async prompting() {
37
    this.answers = await this.prompt([
38
      {
39
        type: "input",
40
        name: "name",
41
        message: "Your project name",
42
        default: this.appname
43
      }
44
    ]);
45
  }
46

47
  writing() {
48
    this.fs.copy(
49
      this.templatePath("index.js"),
50
      this.destinationPath("src/index.js")
51
    );
52
    
53
    this.renderTemplate(
54
      "package.json",
55
      "package.json",
56
      { name: this.answers.name }
57
    );
58
  }
59

60
  async install() {
61
    await this.spawnCommand("npm", ["install"]);
62
  }
63
}
64
```
65

66
## Architecture
67

68
Yeoman Generator is built around several key components:
69

70
- **Generator Lifecycle**: Predefined execution queues (initializing, prompting, configuring, default, writing, transform, conflicts, install, end)
71
- **Mixin System**: Functional mixins that extend the base generator with specialized capabilities
72
- **File System**: mem-fs-editor integration for in-memory file operations with conflict resolution
73
- **Configuration Storage**: Persistent storage system using JSON files for user preferences and project configuration
74
- **Task System**: Queue-based task execution with custom priorities and composition support
75
- **User Interaction**: Inquirer.js integration for interactive prompts with storage and prefilling
76

77
## Capabilities
78

79
### Core Generator System
80

81
The foundational Generator class and lifecycle management system that orchestrates the entire scaffolding process.
82

83
```typescript { .api }
84
export default class Generator<
85
  O extends BaseOptions = BaseOptions,
86
  F extends BaseFeatures = BaseFeatures
87
> extends BaseGenerator<O, F> {
88
  constructor(options: O, features?: F);
89
  constructor(args: string[], options: O, features?: F);
90
  
91
  readonly options: O;
92
  readonly env: Environment;
93
  readonly fs: MemFsEditor;
94
  readonly log: Logger;
95
  readonly args: string[];
96
  readonly appname: string;
97
  readonly config: Storage;
98
  readonly packageJson: Storage;
99
  readonly yoGeneratorVersion: string;
100
  readonly simpleGit: SimpleGit;
101
  
102
  run(): Promise<void>;
103
}
104
```
105

106
[Core Generator System](./core-generator.md)
107

108
### File System Operations
109

110
Template rendering, file copying, and destination management with support for EJS templating and conflict resolution.
111

112
```typescript { .api }
113
function renderTemplate<D>(
114
  source: string | string[],
115
  destination?: string | string[],
116
  templateData?: string | D,
117
  templateOptions?: TemplateOptions,
118
  copyOptions?: CopyOptions
119
): void;
120

121
function copyTemplate(...args: Parameters<MemFsEditor['copy']>): ReturnType<MemFsEditor['copy']>;
122
function readDestination(...args: Parameters<MemFsEditor['read']>): ReturnType<MemFsEditor['read']>;
123
function writeDestination(...args: Parameters<MemFsEditor['write']>): ReturnType<MemFsEditor['write']>;
124
```
125

126
[File System Operations](./file-system.md)
127

128
### User Interaction & Prompting
129

130
Interactive prompting system with storage, prefilling, and validation capabilities built on Inquirer.js.
131

132
```typescript { .api }
133
async prompt<A extends PromptAnswers = PromptAnswers>(
134
  questions: PromptQuestions<A>,
135
  storage?: string | Storage
136
): Promise<A>;
137

138
function registerConfigPrompts(questions: QuestionRegistrationOptions[]): void;
139
```
140

141
[User Interaction & Prompting](./user-interaction.md)
142

143
### Configuration Management
144

145
Persistent storage system for generator configurations, user preferences, and project settings.
146

147
```typescript { .api }
148
class Storage {
149
  constructor(name: string | undefined, fs: MemFsEditor, configPath: string, options?: StorageOptions);
150
  
151
  get<T>(key: string): T;
152
  set<V>(key: string | number | V, value?: V): V | undefined;
153
  getAll(): StorageRecord;
154
  merge(source: StorageRecord): StorageRecord;
155
  createStorage(path: string): Storage;
156
}
157
```
158

159
[Configuration Management](./configuration.md)
160

161
### Command Line Interface
162

163
Options and arguments definition system with parsing, validation, and help generation.
164

165
```typescript { .api }
166
function option(name: string | CliOptionSpec | CliOptionSpec[], config?: Partial<Omit<CliOptionSpec, 'name'>>): this;
167
function argument(name: string, config?: Partial<ArgumentSpec>): this;
168
function help(): string;
169
function usage(): string;
170
```
171

172
[Command Line Interface](./command-line.md)
173

174
### Task & Lifecycle Management
175

176
Queue-based task execution system with custom priorities, composition, and lifecycle management.
177

178
```typescript { .api }
179
function queueTask(task: Task): void;
180
function composeWith<G extends BaseGenerator = BaseGenerator>(
181
  generator: string | { Generator: any; path: string },
182
  options?: ComposeOptions<G>
183
): Promise<G | G[]>;
184
```
185

186
[Task & Lifecycle Management](./task-lifecycle.md)
187

188
### Package Management
189

190
Package.json manipulation and dependency resolution with version management.
191

192
```typescript { .api }
193
async function addDependencies(dependencies: string | string[] | Record<string, string>): Promise<Record<string, string>>;
194
async function addDevDependencies(devDependencies: string | string[] | Record<string, string>): Promise<Record<string, string>>;
195
```
196

197
[Package Management](./package-management.md)
198

199
### Command Execution
200

201
Process spawning and command execution with both synchronous and asynchronous support.
202

203
```typescript { .api }
204
function spawnCommand(command: string, options?: ExecaOptions): ExecaChildProcess;
205
function spawn(command: string, args?: readonly string[], options?: ExecaOptions): ExecaChildProcess;
206
function spawnCommandSync(command: string, options?: SyncOptions): ExecaSyncReturnValue;
207
```
208

209
[Command Execution](./command-execution.md)
210

211
### Git Integration
212

213
Git utilities for user information and repository operations through simple-git integration.
214

215
```typescript { .api }
216
interface GitUtil {
217
  name(): Promise<string | undefined>;
218
  email(): Promise<string | undefined>;
219
}
220

221
readonly git: GitUtil;
222
readonly simpleGit: SimpleGit;
223
```
224

225
[Git Integration](./git-integration.md)
226

227
## Types
228

229
```typescript { .api }
230
interface BaseOptions {
231
  destinationRoot?: string;
232
  skipInstall?: boolean;
233
  skipCheckEnv?: boolean;
234
  ignoreVersionCheck?: boolean;
235
  askAnswered?: boolean;
236
  localConfigOnly?: boolean;
237
  skipCache?: boolean;
238
  skipLocalCache?: boolean;
239
  description?: string;
240
}
241

242
interface BaseFeatures {
243
  uniqueBy?: string;
244
  unique?: true | 'argument' | 'namespace';
245
  tasksMatchingPriority?: boolean;
246
  taskPrefix?: string;
247
  customInstallTask?: boolean | ((...args: any[]) => void | Promise<void>);
248
  customCommitTask?: boolean | ((...args: any[]) => void | Promise<void>);
249
  skipParseOptions?: boolean;
250
  customPriorities?: Priority[];
251
  inheritTasks?: boolean;
252
}
253

254
interface CliOptionSpec {
255
  name: string;
256
  type: typeof Boolean | typeof String | typeof Number | ((opt: string) => any);
257
  required?: boolean;
258
  alias?: string;
259
  default?: any;
260
  description?: string;
261
  hide?: boolean;
262
  storage?: string | Storage;
263
}
264

265
interface ArgumentSpec {
266
  name: string;
267
  description?: string;
268
  required?: boolean;
269
  optional?: boolean;
270
  type: typeof String | typeof Number | typeof Array | typeof Object;
271
  default?: any;
272
}
273

274
type StorageValue = string | number | boolean | null | undefined | StorageValue[] | StorageRecord;
275
type StorageRecord = Record<string, StorageValue>;
276
```