0
# Plop
1

2
Plop is a micro-generator framework that makes it easy for development teams to create files with consistent patterns and structures. It combines interactive command-line prompts with Handlebars templates to automate the generation of boilerplate code, components, routes, controllers, and other repetitive file structures. By codifying file creation patterns, Plop helps maintain coding standards and best practices across teams.
3

4
## Package Information
5

6
- **Package Name**: plop
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -g plop` or `npm install --save-dev plop`
10

11
## Core Imports
12

13
For CLI programmatic usage:
14

15
```javascript
16
import { Plop, run } from "plop";
17
```
18

19
For advanced programmatic usage (direct node-plop access):
20

21
```javascript
22
import { nodePlop } from "plop";
23
// or
24
import nodePlop from "node-plop";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { Plop, run } = require("plop");
31
const { nodePlop } = require("plop");
32
```
33

34
For CLI usage, no imports needed - use the `plop` command directly.
35

36
## Basic Usage
37

38
### CLI Usage
39

40
```bash
41
# Install globally
42
npm install -g plop
43

44
# Run plop (shows generator list)
45
plop
46

47
# Run specific generator
48
plop component
49

50
# Run generator with bypass data
51
plop component "MyComponent"
52
```
53

54
### Programmatic Usage
55

56
```javascript
57
import { Plop, run } from "plop";
58
import path from "node:path";
59

60
// Prepare and execute plop programmatically
61
Plop.prepare({
62
  cwd: process.cwd(),
63
  configPath: path.join(__dirname, 'plopfile.js'),
64
}, env => Plop.execute(env, run));
65
```
66

67
## Architecture
68

69
Plop is built around several key components:
70

71
- **CLI Interface**: Primary user interaction through terminal commands with argument parsing and help system
72
- **Liftoff Integration**: Configuration file discovery and environment setup for finding plopfiles
73
- **Generator System**: Integration with node-plop for executing generators with prompts and actions
74
- **Progress Feedback**: Visual progress indicators using Ora spinners during file generation
75
- **Bypass System**: Allows skipping prompts by providing values directly via CLI arguments
76

77
## Capabilities
78

79
### Command Line Interface
80

81
Full-featured CLI for running generators interactively or with bypass data. Includes help system, version information, and initialization commands.
82

83
```javascript { .api }
84
// CLI entry point from bin/plop.js
85
import { Plop, run } from "../src/plop.js";
86

87
Plop.prepare(options, function (env) {
88
  Plop.execute(env, run);
89
});
90
```
91

92
[Command Line Interface](./cli.md)
93

94
### Programmatic Execution
95

96
Core execution functions for embedding Plop functionality in custom tools and workflows.
97

98
```javascript { .api }
99
/**
100
 * Main execution function for plop generators
101
 * @param env - Environment object from Liftoff containing configuration
102
 * @param _ - Unused parameter for compatibility
103
 * @param passArgsBeforeDashes - Optional boolean to merge CLI and generator args
104
 * @returns Promise resolving to plop instance
105
 */
106
async function run(env, _, passArgsBeforeDashes);
107

108
/**
109
 * Liftoff instance configured for plop
110
 */
111
const Plop: Liftoff;
112

113
/**
114
 * Ora spinner instance for progress indication
115
 */
116
const progressSpinner: ora.Ora;
117
```
118

119
[Programmatic Usage](./programmatic.md)
120

121
### Generator Management API
122

123
Comprehensive programmatic API for creating, configuring, and executing code generators through the node-plop package.
124

125
```javascript { .api }
126
/**
127
 * Create a new NodePlopAPI instance
128
 * @param plopfilePath - Optional absolute path to plopfile
129
 * @param plopCfg - Optional configuration object
130
 * @returns Promise resolving to NodePlopAPI instance
131
 */
132
function nodePlop(plopfilePath?: string, plopCfg?: PlopCfg): Promise<NodePlopAPI>;
133

134
/**
135
 * Register a new generator
136
 * @param name - Unique generator name
137
 * @param config - Generator configuration
138
 * @returns PlopGenerator instance
139
 */
140
setGenerator(name: string, config: Partial<PlopGeneratorConfig>): PlopGenerator;
141

142
/**
143
 * Execute generator prompts and actions
144
 * @param bypassArr - Optional array to bypass prompts
145
 * @returns Promise resolving to user answers
146
 */
147
runPrompts(bypassArr?: string[]): Promise<any>;
148
```
149

150
[Generator Management](./generator-api.md)
151

152
### Template System
153

154
Handlebars templating with built-in helpers, custom helpers, and partials for flexible file generation.
155

156
```javascript { .api }
157
/**
158
 * Register a custom Handlebars helper
159
 * @param name - Helper name for use in templates
160
 * @param fn - Helper function
161
 */
162
setHelper(name: string, fn: HelperFunction): void;
163

164
/**
165
 * Register a Handlebars partial
166
 * @param name - Partial name for use in templates
167
 * @param str - Partial template string
168
 */
169
setPartial(name: string, str: string): void;
170

171
/**
172
 * Render a Handlebars template string with data
173
 * @param template - Handlebars template string
174
 * @param data - Data object for template rendering
175
 * @returns Rendered string
176
 */
177
renderString(template: string, data: any): string;
178
```
179

180
[Template System](./template-system.md)
181

182
### Action System 
183

184
Built-in file operations (add, addMany, modify, append) and support for custom actions.
185

186
```javascript { .api }
187
/**
188
 * Register a custom action type
189
 * @param name - Action type name
190
 * @param fn - Action function
191
 */
192
setActionType(name: string, fn: CustomActionFunction): void;
193

194
// Built-in action configuration interfaces
195
interface AddActionConfig extends ActionConfig {
196
  type: "add";
197
  path: string;
198
  skipIfExists?: boolean;
199
} & TemplateStrOrFile;
200

201
interface ModifyActionConfig extends ActionConfig {
202
  type: "modify";
203
  path: string;
204
  pattern: string | RegExp;
205
} & TemplateStrOrFile;
206
```
207

208
[Action System](./action-system.md)
209

210
### Console Output and User Interface
211

212
User interface functions for displaying help, selecting generators, and creating initial plopfiles.
213

214
```javascript { .api }
215
/**
216
 * Display generator selection list to user
217
 * @param plopList - Array of available generators
218
 * @param message - Optional custom selection message
219
 * @returns Promise resolving to selected generator name
220
 */
221
async function chooseOptionFromList(plopList, message);
222

223
/**
224
 * Display help screen with usage information
225
 */
226
function displayHelpScreen();
227

228
/**
229
 * Create initial plopfile.js or plopfile.ts
230
 * @param force - Overwrite existing plopfile if present
231
 * @param useTypescript - Generate TypeScript plopfile
232
 */
233
function createInitPlopfile(force, useTypescript);
234
```
235

236
[Console Interface](./console.md)
237

238
## Types
239

240
```javascript { .api }
241
// Core configuration types
242
interface PlopCfg {
243
  force?: boolean;           // Force overwrite existing files
244
  destBasePath?: string;     // Base path for file operations
245
}
246

247
interface PlopGeneratorConfig {
248
  description: string;       // Human-readable description
249
  prompts: Prompts;         // Inquirer prompts or function
250
  actions: Actions;         // Actions to perform or function
251
}
252

253
// Generator and API interfaces
254
interface NodePlopAPI {
255
  setGenerator(name: string, config: Partial<PlopGeneratorConfig>): PlopGenerator;
256
  getGenerator(name: string): PlopGenerator;
257
  getGeneratorList(): { name: string; description: string }[];
258
  setHelper(name: string, fn: HelperFunction): void;
259
  setPartial(name: string, str: string): void;
260
  setActionType(name: string, fn: CustomActionFunction): void;
261
  renderString(template: string, data: any): string;
262
}
263

264
interface PlopGenerator extends PlopGeneratorConfig {
265
  runPrompts(bypassArr?: string[]): Promise<any>;
266
  runActions(answers: Answers, hooks?: PlopActionHooks): Promise<{
267
    changes: PlopActionHooksChanges[];
268
    failures: PlopActionHooksFailures[];
269
  }>;
270
}
271

272
// Action configuration types
273
interface ActionConfig {
274
  type: string;             // Action type name
275
  force?: boolean;          // Force overwrite
276
  data?: object;            // Additional template data
277
  abortOnFail?: boolean;    // Abort on action failure
278
  skip?: Function;          // Conditional skip function
279
}
280

281
interface AddActionConfig extends ActionConfig {
282
  type: "add";
283
  path: string;
284
  skipIfExists?: boolean;
285
} & TemplateStrOrFile;
286

287
interface AddManyActionConfig extends ActionConfig {
288
  type: "addMany";
289
  destination: string;
290
  base: string;
291
  templateFiles: string | string[];
292
  stripExtensions?: string[];
293
  globOptions?: GlobOptions;
294
  verbose?: boolean;
295
}
296

297
interface ModifyActionConfig extends ActionConfig {
298
  type: "modify";
299
  path: string;
300
  pattern: string | RegExp;
301
} & TemplateStrOrFile;
302

303
interface AppendActionConfig extends ActionConfig {
304
  type: "append";
305
  path: string;
306
  pattern: string | RegExp;
307
  unique?: boolean;
308
  separator?: string;
309
} & TemplateStrOrFile;
310

311
// Template and prompt types
312
interface TemplateStrOrFile {
313
  template?: string;        // Inline template string
314
  templateFile?: string;    // Path to template file
315
}
316

317
type Prompts = DynamicPromptsFunction | PromptQuestion[];
318
type Actions = DynamicActionsFunction | ActionType[];
319
type ActionType = AddActionConfig | AddManyActionConfig | ModifyActionConfig | AppendActionConfig | CustomActionConfig<string>;
320

321
type DynamicPromptsFunction = (inquirer: Inquirer) => Promise<Answers>;
322
type DynamicActionsFunction = (data?: Answers) => ActionType[];
323
type CustomActionFunction = (
324
  answers: Answers,
325
  config: CustomActionConfig<string>,
326
  plopfileApi: NodePlopAPI,
327
) => Promise<string> | string;
328

329
// Hook system types
330
interface PlopActionHooks {
331
  onComment?: (msg: string) => void;
332
  onSuccess?: (change: PlopActionHooksChanges) => void;
333
  onFailure?: (failure: PlopActionHooksFailures) => void;
334
}
335

336
interface PlopActionHooksChanges {
337
  type: string;
338
  path: string;
339
}
340

341
interface PlopActionHooksFailures {
342
  type: string;
343
  path: string;
344
  error: string;
345
  message: string;
346
}
347

348
// CLI and environment types
349
interface EnvironmentOptions {
350
  cwd?: string;
351
  preload?: string[];
352
  configPath?: string;
353
  completion?: any;
354
}
355

356
interface GeneratorInfo {
357
  name: string;
358
  description?: string;
359
}
360

361
// External library types
362
interface Liftoff {
363
  prepare(options: PrepareOptions, callback: (env: LiftoffEnvironment) => void): void;
364
  execute(env: LiftoffEnvironment, run: Function): any;
365
}
366

367
interface PrepareOptions {
368
  cwd?: string;
369
  preload?: string[];
370
  configPath?: string;
371
  completion?: any;
372
}
373

374
interface LiftoffEnvironment {
375
  configPath: string;
376
  cwd: string;
377
  require: Function;
378
  configName: string;
379
  configBase: string;
380
  configNameSearch: string[];
381
  modulePackage: object;
382
  modules: object;
383
}
384

385
interface Ora {
386
  start(): Ora;
387
  stop(): Ora;
388
  succeed(text?: string): Ora;
389
  fail(text?: string): Ora;
390
  info(text?: string): Ora;
391
}
392
```