0
# Generator API
1

2
Plop provides a comprehensive programmatic API for creating, configuring, and executing code generators. This API is primarily provided by the node-plop package that plop re-exports.
3

4
## Capabilities
5

6
### NodePlopAPI Creation
7

8
Create a new plop API instance for programmatic generator management.
9

10
```javascript { .api }
11
/**
12
 * Create a new NodePlopAPI instance
13
 * @param plopfilePath - Optional absolute path to plopfile
14
 * @param plopCfg - Optional configuration object
15
 * @returns Promise resolving to NodePlopAPI instance
16
 */
17
function nodePlop(plopfilePath?: string, plopCfg?: PlopCfg): Promise<NodePlopAPI>;
18

19
interface PlopCfg {
20
  force?: boolean;           // Force overwrite existing files
21
  destBasePath?: string;     // Base path for file operations
22
}
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import { nodePlop } from "plop";
29

30
// Create instance without plopfile
31
const plop = await nodePlop();
32

33
// Create instance with specific plopfile
34
const plop = await nodePlop('/path/to/plopfile.js');
35

36
// Create instance with configuration
37
const plop = await nodePlop('./plopfile.js', {
38
  force: true,
39
  destBasePath: './output'
40
});
41
```
42

43
### Generator Management
44

45
Create and manage code generators programmatically.
46

47
```javascript { .api }
48
/**
49
 * Register a new generator with the plop instance
50
 * @param name - Unique generator name
51
 * @param config - Generator configuration object
52
 * @returns PlopGenerator instance
53
 */
54
setGenerator(name: string, config: Partial<PlopGeneratorConfig>): PlopGenerator;
55

56
/**
57
 * Retrieve a registered generator by name
58
 * @param name - Generator name
59
 * @returns PlopGenerator instance or undefined
60
 */
61
getGenerator(name: string): PlopGenerator;
62

63
/**
64
 * Get list of all registered generators
65
 * @returns Array of generator info objects
66
 */
67
getGeneratorList(): { name: string; description: string }[];
68
```
69

70
**Generator Configuration:**
71

72
```javascript { .api }
73
interface PlopGeneratorConfig {
74
  description: string;       // Human-readable description
75
  prompts: Prompts;         // Inquirer prompts or function
76
  actions: Actions;         // Actions to perform or function
77
}
78

79
type Prompts = DynamicPromptsFunction | PromptQuestion[];
80
type Actions = DynamicActionsFunction | ActionType[];
81
```
82

83
**Usage Examples:**
84

85
```javascript
86
import { nodePlop } from "plop";
87

88
const plop = await nodePlop();
89

90
// Register a component generator
91
const componentGen = plop.setGenerator('component', {
92
  description: 'React component generator',
93
  prompts: [
94
    {
95
      type: 'input',
96
      name: 'name',
97
      message: 'Component name:'
98
    },
99
    {
100
      type: 'list',
101
      name: 'type',
102
      message: 'Component type:',
103
      choices: ['functional', 'class']
104
    }
105
  ],
106
  actions: [
107
    {
108
      type: 'add',
109
      path: 'src/components/{{name}}.jsx',
110
      templateFile: 'templates/component.hbs'
111
    }
112
  ]
113
});
114

115
// Get generator by name
116
const gen = plop.getGenerator('component');
117

118
// List all generators
119
const generators = plop.getGeneratorList();
120
console.log(generators);
121
// [{ name: 'component', description: 'React component generator' }]
122
```
123

124
### Generator Execution
125

126
Execute generators programmatically with prompt handling and action processing.
127

128
```javascript { .api }
129
interface PlopGenerator extends PlopGeneratorConfig {
130
  /**
131
   * Run generator prompts and collect user input
132
   * @param bypassArr - Optional array to bypass prompts with pre-filled answers
133
   * @returns Promise resolving to user answers
134
   */
135
  runPrompts(bypassArr?: string[]): Promise<any>;
136
  
137
  /**
138
   * Execute generator actions with provided answers
139
   * @param answers - Answers from prompts or provided data
140
   * @param hooks - Optional lifecycle hooks
141
   * @returns Promise resolving to execution results
142
   */
143
  runActions(answers: Answers, hooks?: PlopActionHooks): Promise<{
144
    changes: PlopActionHooksChanges[];
145
    failures: PlopActionHooksFailures[];
146
  }>;
147
}
148
```
149

150
**Action Hooks Interface:**
151

152
```javascript { .api }
153
interface PlopActionHooks {
154
  onComment?: (msg: string) => void;
155
  onSuccess?: (change: PlopActionHooksChanges) => void;
156
  onFailure?: (failure: PlopActionHooksFailures) => void;
157
}
158

159
interface PlopActionHooksChanges {
160
  type: string;             // Action type that succeeded
161
  path: string;             // File path that was changed
162
}
163

164
interface PlopActionHooksFailures {
165
  type: string;             // Action type that failed
166
  path: string;             // File path that failed
167
  error: string;            // Error message
168
  message: string;          // Human-readable message
169
}
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
const plop = await nodePlop('./plopfile.js');
176
const generator = plop.getGenerator('component');
177

178
// Run with interactive prompts
179
const answers = await generator.runPrompts();
180

181
// Run with bypass data (skip prompts)
182
const answers = await generator.runPrompts(['MyComponent', 'functional']);
183

184
// Execute actions with hooks
185
const results = await generator.runActions(answers, {
186
  onSuccess: (change) => console.log(`✅ ${change.type}: ${change.path}`),
187
  onFailure: (failure) => console.error(`❌ ${failure.type}: ${failure.error}`),
188
  onComment: (msg) => console.log(`💬 ${msg}`)
189
});
190

191
console.log(`${results.changes.length} files changed`);
192
console.log(`${results.failures.length} failures`);
193
```
194

195
### Dynamic Configuration
196

197
Use functions to dynamically configure prompts and actions based on runtime conditions.
198

199
```javascript { .api }
200
/**
201
 * Function that returns prompts dynamically
202
 * @param inquirer - Inquirer instance for advanced prompt handling
203
 * @returns Promise resolving to prompt answers
204
 */
205
type DynamicPromptsFunction = (inquirer: Inquirer) => Promise<Answers>;
206

207
/**
208
 * Function that returns actions dynamically based on answers
209
 * @param data - Answers from prompts
210
 * @returns Array of actions to execute
211
 */
212
type DynamicActionsFunction = (data?: Answers) => ActionType[];
213
```
214

215
**Usage Examples:**
216

217
```javascript
218
plop.setGenerator('advanced', {
219
  description: 'Advanced generator with dynamic configuration',
220
  
221
  // Dynamic prompts based on conditions
222
  prompts: async (inquirer) => {
223
    const answers = {};
224
    
225
    // Conditional prompting
226
    answers.type = await inquirer.prompt({
227
      type: 'list',
228
      name: 'type',
229
      choices: ['api', 'ui', 'test']
230
    });
231
    
232
    if (answers.type === 'api') {
233
      answers.methods = await inquirer.prompt({
234
        type: 'checkbox',
235
        name: 'methods',
236
        choices: ['GET', 'POST', 'PUT', 'DELETE']
237
      });
238
    }
239
    
240
    return answers;
241
  },
242
  
243
  // Dynamic actions based on answers
244
  actions: (data) => {
245
    const actions = [
246
      {
247
        type: 'add',
248
        path: `src/${data.type}/{{name}}.js`,
249
        templateFile: `templates/${data.type}.hbs`
250
      }
251
    ];
252
    
253
    if (data.type === 'api' && data.methods.includes('POST')) {
254
      actions.push({
255
        type: 'add',
256
        path: `src/${data.type}/{{name}}.test.js`,
257
        templateFile: 'templates/api-test.hbs'
258
      });
259
    }
260
    
261
    return actions;
262
  }
263
});
264
```
265

266
## Path Management
267

268
Control file system paths and destination handling.
269

270
```javascript { .api }
271
/**
272
 * Set the path to the plopfile for this instance
273
 * @param filePath - Absolute path to plopfile
274
 */
275
setPlopfilePath(filePath: string): void;
276

277
/**
278
 * Get the current plopfile path
279
 * @returns Current plopfile path
280
 */
281
getPlopfilePath(): string;
282

283
/**
284
 * Get the base destination path for file operations
285
 * @returns Base destination path
286
 */
287
getDestBasePath(): string;
288
```
289

290
## Template Rendering
291

292
Render Handlebars templates with data outside of action context.
293

294
```javascript { .api }
295
/**
296
 * Render a Handlebars template string with provided data
297
 * @param template - Handlebars template string
298
 * @param data - Data object for template rendering
299
 * @returns Rendered string
300
 */
301
renderString(template: string, data: any): string;
302
```
303

304
**Usage Examples:**
305

306
```javascript
307
const plop = await nodePlop();
308

309
// Render template with data
310
const template = 'Hello {{name}}, welcome to {{project}}!';
311
const rendered = plop.renderString(template, {
312
  name: 'Alice',
313
  project: 'My App'
314
});
315
console.log(rendered); // "Hello Alice, welcome to My App!"
316

317
// Use with path templates
318
const pathTemplate = 'src/components/{{kebabCase name}}/{{pascalCase name}}.jsx';
319
const path = plop.renderString(pathTemplate, { name: 'MyComponent' });
320
console.log(path); // "src/components/my-component/MyComponent.jsx"
321
```