0
# Yeoman Environment
1

2
Yeoman Environment is a TypeScript library that handles the lifecycle and bootstrapping of generators in a specific environment. It provides a high-level API to discover, create, and run generators with advanced configuration options for resolver behavior and runtime environment management. The package serves as the core infrastructure for Yeoman's scaffolding system, providing the runtime environment that coordinates between generators and the user's development workspace.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import Environment, { 
15
  createEnv, 
16
  EnvironmentBase,
17
  YeomanCommand,
18
  lookupGenerator,
19
  addEnvironmentOptions,
20
  prepareCommand,
21
  prepareGeneratorCommand,
22
  commitSharedFsTask,
23
  packageManagerInstallTask,
24
  removePropertiesWithNullishValues,
25
  moduleLookupSync,
26
  findPackagesIn,
27
  getNpmPaths,
28
  defaultExtensions,
29
  UNKNOWN_NAMESPACE,
30
  UNKNOWN_RESOLVED,
31
  defaultQueues
32
} from "yeoman-environment";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const Environment = require("yeoman-environment").default;
39
const { 
40
  createEnv, 
41
  EnvironmentBase,
42
  YeomanCommand,
43
  lookupGenerator,
44
  addEnvironmentOptions,
45
  prepareCommand,
46
  prepareGeneratorCommand,
47
  commitSharedFsTask,
48
  packageManagerInstallTask,
49
  removePropertiesWithNullishValues,
50
  moduleLookupSync,
51
  findPackagesIn,
52
  getNpmPaths,
53
  defaultExtensions,
54
  UNKNOWN_NAMESPACE,
55
  UNKNOWN_RESOLVED,
56
  defaultQueues
57
} = require("yeoman-environment");
58
```
59

60
## Basic Usage
61

62
```typescript
63
import { createEnv } from "yeoman-environment";
64

65
// Create environment instance
66
const env = createEnv();
67

68
// Search for installed generators
69
await env.lookup();
70

71
// Run a generator
72
await env.run("angular", { skipInstall: true });
73

74
// Execute a specific generator with arguments
75
await env.execute("app:component", ["UserCard", "--style=css"]);
76
```
77

78
## Architecture
79

80
Yeoman Environment is built around several key components:
81

82
- **Environment Classes**: Core environment management (`Environment`, `EnvironmentBase`)
83
- **Generator Registry**: Storage and metadata system for discovered generators
84
- **Lookup System**: Discovery mechanisms for finding installed generators
85
- **Command Integration**: CLI support via Commander.js extensions
86
- **File System Management**: Memory filesystem integration for generator operations
87
- **Package Manager Integration**: Automatic dependency installation handling
88
- **Conflict Resolution**: File conflict handling and resolution strategies
89

90
## Capabilities
91

92
### Environment Management
93

94
Core environment functionality for managing generator lifecycles, registration, and execution.
95

96
```typescript { .api }
97
function createEnv(options?: EnvironmentOptions): Environment;
98

99
class Environment extends EnvironmentBase {
100
  constructor(options?: EnvironmentOptions);
101
  help(name?: string): string;
102
  execute(generatorNamespace: string, args?: string[]): Promise<void>;
103
  requireGenerator(namespace: string): Promise<BaseGeneratorConstructor | undefined>;
104
  installLocalGenerators(packages: Record<string, string | undefined>): Promise<boolean>;
105
  lookupLocalPackages(packagesToLookup?: string[]): Promise<void>;
106
  run(args?: string[], options?: any): Promise<void>;
107
}
108

109
interface EnvironmentOptions extends BaseEnvironmentOptions {
110
  adapter?: InputOutputAdapter;
111
  logCwd?: string;
112
  command?: YeomanCommand;
113
  yeomanRepository?: string;
114
  arboristRegistry?: string;
115
  nodePackageManager?: string;
116
}
117
```
118

119
[Environment Management](./environment.md)
120

121
### Generator Discovery
122

123
Generator discovery and lookup system for finding installed generators across various locations.
124

125
```typescript { .api }
126
function lookupGenerator(
127
  namespace: string,
128
  options?: ModuleLookupOptions & {
129
    packagePath?: boolean;
130
    generatorPath?: boolean;
131
  }
132
): string | string[];
133

134
interface LookupOptions extends LookupOptionsApi {
135
  lookups?: string[];
136
  localOnly?: boolean;
137
  packagePaths?: string | string[];
138
  npmPaths?: string | string[];
139
  filePatterns?: string | string[];
140
  packagePatterns?: string | string[];
141
  singleResult?: boolean;
142
}
143
```
144

145
[Generator Discovery](./generator-discovery.md)
146

147
### Generator Management
148

149
Registration, instantiation, and execution of generators with metadata management.
150

151
```typescript { .api }
152
interface BaseEnvironment {
153
  register(pathOrStub: unknown, meta?: Partial<BaseGeneratorMeta>): GeneratorMeta;
154
  get<C>(namespaceOrPath: string | YeomanNamespace): Promise<C | undefined>;
155
  create<G>(namespaceOrPath: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
156
  instantiate<G>(generator: GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
157
  composeWith<G>(generator: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
158
  runGenerator(generator: BaseGenerator): Promise<void>;
159
  queueGenerator<G>(generator: G, queueOptions?: { schedule?: boolean }): Promise<G>;
160
}
161
```
162

163
[Generator Management](./generator-management.md)
164

165
### Command Line Interface
166

167
CLI command creation and management with Commander.js integration for generator commands.
168

169
```typescript { .api }
170
class YeomanCommand extends Command {
171
  env?: BaseEnvironment;
172
  createCommand(name?: string): YeomanCommand;
173
  addOption(option: Option): YeomanCommand;
174
  registerGenerator(generator: any): YeomanCommand;
175
  addGeneratorArguments(generatorArgs: any[]): YeomanCommand;
176
  addGeneratorOptions(options: Record<string, any>): YeomanCommand;
177
}
178

179
function addEnvironmentOptions(command?: YeomanCommand): YeomanCommand;
180
function prepareCommand(options: CommandPreparation): Promise<YeomanCommand>;
181
function prepareGeneratorCommand(options: CommandPreparation): Promise<YeomanCommand>;
182

183
interface CommandPreparation {
184
  resolved?: string;
185
  command?: YeomanCommand;
186
  generator?: BaseGeneratorConstructor;
187
  namespace?: string;
188
}
189
```
190

191
[Command Line Interface](./cli.md)
192

193
### File System Operations
194

195
Memory filesystem operations, conflict resolution, and file transforms for generator output.
196

197
```typescript { .api }
198
function commitSharedFsTask(options: {
199
  adapter: InputOutputAdapter;
200
  conflicterOptions?: ConflicterOptions;
201
  sharedFs: Store<MemFsEditorFile>;
202
}): Promise<void>;
203

204
function packageManagerInstallTask(options: PackageManagerInstallTaskOptions): Promise<boolean>;
205

206
interface PackageManagerInstallTaskOptions {
207
  memFs: Store<MemFsEditorFile>;
208
  packageJsonLocation: string;
209
  adapter: InputOutputAdapter;
210
  nodePackageManager?: string;
211
  customInstallTask?: boolean | ((nodePackageManager: string | undefined, defaultTask: () => Promise<boolean>) => void | Promise<void>);
212
  skipInstall?: boolean;
213
}
214
```
215

216
[File System Operations](./filesystem.md)
217

218
### Utility Functions
219

220
Utility functions for data manipulation and environment operations.
221

222
```typescript { .api }
223
function removePropertiesWithNullishValues(object: Record<string, any>): Record<string, any>;
224
```
225

226
### Module Discovery
227

228
Module and package discovery utilities for finding generators in npm packages.
229

230
```typescript { .api }
231
function moduleLookupSync(patterns: string | string[], options?: {
232
  packageJson?: boolean;
233
  singleResult?: boolean;
234
  lookups?: string[];
235
  npmPaths?: string | string[];
236
}): string | string[];
237

238
function findPackagesIn(
239
  patterns: string | string[],
240
  searchPaths: string[]
241
): string[];
242

243
function getNpmPaths(paths?: string | string[]): string[];
244
```
245

246
[Module Discovery](./module-lookup.md)
247

248
### Constants
249

250
Predefined constants used throughout the environment system.
251

252
```typescript { .api }
253
const defaultExtensions: string[];
254
const UNKNOWN_NAMESPACE: string;
255
const UNKNOWN_RESOLVED: string;
256
const defaultQueues: string[];
257
```
258

259
## Common Types
260

261
```typescript { .api }
262
interface BaseGeneratorMeta {
263
  namespace: string;
264
  resolved?: string;
265
  packagePath?: string;
266
}
267

268
interface GeneratorMeta extends BaseGeneratorMeta {
269
  instantiate(...args: any[]): Promise<BaseGenerator>;
270
  instantiateHelp(): Promise<BaseGenerator>;
271
}
272

273
interface EnvironmentLookupOptions extends LookupOptions {
274
  registerToScope?: string;
275
  customizeNamespace?: (ns?: string) => string | undefined;
276
}
277

278
type YeomanNamespace = {
279
  packageNamespace: string;
280
  generator?: string;
281
  scope?: string;
282
  instanceId?: string;
283
};
284

285
interface BaseEnvironmentOptions {
286
  cwd?: string;
287
  skipInstall?: boolean;
288
  forceInstall?: boolean;
289
  skipCache?: boolean;
290
  skipLocalCache?: boolean;
291
  skipParseOptions?: boolean;
292
  localConfigOnly?: boolean;
293
  askAnswered?: boolean;
294
}
295

296
interface LookupOptionsApi {
297
  lookups?: string[];
298
  localOnly?: boolean;
299
  packagePaths?: string | string[];
300
  npmPaths?: string | string[];
301
  filePatterns?: string | string[];
302
  packagePatterns?: string | string[];
303
  singleResult?: boolean;
304
}
305

306
interface InputOutputAdapter {
307
  log: {
308
    write(message?: string): void;
309
    writeln(message?: string): void;
310
    ok(message?: string): void;
311
    error(message?: string): void;
312
    info(message?: string): void;
313
    warning(message?: string): void;
314
  };
315
  prompt: (questions: any) => Promise<any>;
316
}
317

318
interface BaseGeneratorConstructor {
319
  new (...args: any[]): BaseGenerator;
320
}
321

322
interface BaseGenerator {
323
  arguments: string[];
324
  options: Record<string, any>;
325
  run(): Promise<void>;
326
}
327

328
interface Store<T> {
329
  add(file: T): void;
330
  get(path: string): T | undefined;
331
  each(callback: (file: T, path: string) => void): void;
332
}
333

334
interface ConflicterOptions {
335
  force?: boolean;
336
  bail?: boolean;
337
  ignoreWhitespace?: boolean;
338
  regenerateFiles?: boolean;
339
}
340
```