0
# Generator Discovery
1

2
Generator discovery and lookup system for finding installed generators across various locations including npm packages, local generators, and global installations.
3

4
## Capabilities
5

6
### Generator Lookup
7

8
Look up specific generator by namespace with path resolution options.
9

10
```typescript { .api }
11
/**
12
 * Look up specific generator by namespace with path resolution
13
 * @param namespace - Generator namespace to search for
14
 * @param options - Lookup options including path resolution flags
15
 * @returns Generator path(s) or empty if not found
16
 */
17
function lookupGenerator(
18
  namespace: string,
19
  options?: ModuleLookupOptions & {
20
    packagePath?: boolean;
21
    generatorPath?: boolean;
22
  }
23
): string | string[];
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import { lookupGenerator } from "yeoman-environment";
30

31
// Find generator by namespace
32
const generatorPath = lookupGenerator("angular:component");
33

34
// Get package path instead of generator path
35
const packagePath = lookupGenerator("angular:component", { 
36
  packagePath: true 
37
});
38

39
// Get both paths
40
const paths = lookupGenerator("angular:component", { 
41
  packagePath: true,
42
  generatorPath: true 
43
});
44
```
45

46
### Environment Lookup
47

48
Search for generators using the environment's lookup system with comprehensive filtering options.
49

50
```typescript { .api }
51
/**
52
 * Search for generators with filtering and registration options
53
 * This method is available on Environment and EnvironmentBase instances
54
 * @param options - Lookup configuration options
55
 * @returns Array of found generator metadata
56
 */
57
lookup(options?: EnvironmentLookupOptions): Promise<LookupGeneratorMeta[]>;
58
```
59

60
**Usage Example:**
61

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

65
const env = createEnv();
66

67
// Search for all generators
68
const allGenerators = await env.lookup();
69

70
// Search only local generators
71
const localGenerators = await env.lookup({ localOnly: true });
72

73
// Search with custom namespace processing
74
const scopedGenerators = await env.lookup({
75
  registerToScope: "myapp",
76
  customizeNamespace: (ns) => ns?.startsWith("@myorg/") ? ns : undefined
77
});
78

79
// Search specific package patterns
80
const angularGenerators = await env.lookup({
81
  packagePatterns: ["generator-angular*"],
82
  filePatterns: ["generators/*/index.js"]
83
});
84
```
85

86
### Lookup Local Packages
87

88
Discover and register generators from local packages.
89

90
```typescript { .api }
91
/**
92
 * Lookup and register local packages
93
 * Available on Environment instances
94
 * @param packagesToLookup - Optional array of specific packages to lookup
95
 */
96
lookupLocalPackages(packagesToLookup?: string[]): Promise<void>;
97
```
98

99
**Usage Example:**
100

101
```typescript
102
import { createEnv } from "yeoman-environment";
103

104
const env = createEnv();
105

106
// Lookup all local packages
107
await env.lookupLocalPackages();
108

109
// Lookup specific packages
110
await env.lookupLocalPackages([
111
  "generator-webapp",
112
  "generator-node"
113
]);
114
```
115

116
## Configuration Types
117

118
```typescript { .api }
119
interface LookupOptions extends LookupOptionsApi {
120
  /** Lookup paths for generators (defaults: ['.', 'generators', 'lib/generators', 'dist/generators']) */
121
  lookups?: string[];
122
  /** Skip lookups of globally-installed generators */
123
  localOnly?: boolean;
124
  /** Specific paths to look for generators */
125
  packagePaths?: string | string[];
126
  /** Repository paths to look for generator packages */
127
  npmPaths?: string | string[];
128
  /** File patterns to match (e.g., '*/index.js', 'generators/*/index.ts') */
129
  filePatterns?: string | string[];
130
  /** Package patterns to match (e.g., 'generator-*', '@angular/schematics-*') */
131
  packagePatterns?: string | string[];
132
  /** Stop lookup on first match */
133
  singleResult?: boolean;
134
  /** Depth option for globby searches */
135
  globbyDeep?: number;
136
  /** Filter discovered paths */
137
  filterPaths?: boolean;
138
  /** Reverse results (affects override behavior) */
139
  reverse?: boolean;
140
}
141

142
interface EnvironmentLookupOptions extends LookupOptions {
143
  /** Add scope to namespace if missing */
144
  registerToScope?: string;
145
  /** Customize namespace during registration */
146
  customizeNamespace?: (ns?: string) => string | undefined;
147
}
148

149
interface ModuleLookupOptions {
150
  /** Skip lookups of globally-installed generators */
151
  localOnly?: boolean;
152
  /** Specific paths to search */
153
  packagePaths?: string | string[];
154
  /** npm paths to search */
155
  npmPaths?: string | string[];
156
  /** Package patterns to match */
157
  packagePatterns?: string | string[];
158
  /** Stop on first result */
159
  singleResult?: boolean;
160
  /** Additional lookup options */
161
  [key: string]: any;
162
}
163
```
164

165
## Generator Metadata Types
166

167
```typescript { .api }
168
interface LookupGeneratorMeta extends BaseGeneratorMeta {
169
  /** Full file path to the generator */
170
  filePath: string;
171
  /** Path to the package containing the generator */
172
  packagePath: string;
173
  /** Lookup paths used to find this generator */
174
  lookups: string[];
175
}
176

177
interface BaseGeneratorMeta {
178
  /** Generator namespace (e.g., 'angular:component') */
179
  namespace: string;
180
  /** Resolved path to generator file */
181
  resolved?: string;
182
  /** Path to package containing generator */
183
  packagePath?: string;
184
}
185

186
interface GeneratorMeta extends BaseGeneratorMeta {
187
  /** Create generator instance with arguments */
188
  instantiate(...args: any[]): Promise<BaseGenerator>;
189
  /** Create generator instance for help display */
190
  instantiateHelp(): Promise<BaseGenerator>;
191
}
192
```
193

194
## Discovery Process
195

196
The generator discovery system follows this process:
197

198
1. **Search Paths**: Scans configured npm paths and package paths
199
2. **Pattern Matching**: Matches files and packages against configured patterns
200
3. **Namespace Resolution**: Converts file paths to generator namespaces
201
4. **Registration**: Registers discovered generators with metadata
202
5. **Filtering**: Applies custom filters and scoping rules
203

204
### Default Search Locations
205

206
- **Local**: `./node_modules/generator-*`
207
- **Global**: Global npm installation directories
208
- **Custom**: User-specified package paths
209

210
### Default File Patterns
211

212
- `generators/*/index.js`
213
- `generators/*/index.ts`
214
- `lib/generators/*/index.js`
215
- `dist/generators/*/index.js`
216
- `./index.js` (for root generators)
217

218
### Default Package Patterns
219

220
- `generator-*` (Standard Yeoman generator naming)
221
- Custom patterns via configuration
222

223
**Usage Tips:**
224

225
```typescript
226
// Find all React-related generators
227
const reactGenerators = await env.lookup({
228
  packagePatterns: ["*react*", "generator-*react*"],
229
  customizeNamespace: (ns) => ns?.includes("react") ? ns : undefined
230
});
231

232
// Search only TypeScript generators
233
const tsGenerators = await env.lookup({
234
  filePatterns: ["generators/*/index.ts", "*/index.ts"],
235
  packagePatterns: ["generator-*"]
236
});
237

238
// Fast single-result lookup
239
const firstMatch = await env.lookup({
240
  packagePatterns: ["generator-webapp"],
241
  singleResult: true
242
});
243
```