tessl/npm-plop

Micro-generator framework that makes it easy for an entire team to create files with a level of uniformity

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Programmatic Usage

Name: tessl/npm-plop
Author: tessl

Plop can be embedded in custom CLI tools and workflows through its programmatic API, allowing you to wrap plop functionality in your own applications.

Capabilities

Core Execution

Main execution function for running plop generators programmatically.

/**
 * The main execution function for plop generators
 * @param env - Environment object from Liftoff containing configuration
 * @param _ - Unused parameter for compatibility (allows passArgsBeforeDashes to be explicit)
 * @param passArgsBeforeDashes - Optional boolean to merge plop CLI API and generator API
 * @returns Promise resolving to plop instance
 */
async function run(env, _, passArgsBeforeDashes);

Usage Examples:

import { Plop, run } from "plop";

// Standard execution
Plop.prepare({
  cwd: process.cwd(),
  configPath: './plopfile.js'
}, env => Plop.execute(env, run));

// With args merging enabled (passArgsBeforeDashes = true)
Plop.prepare({
  cwd: process.cwd(),
  configPath: './plopfile.js'
}, env => Plop.execute(env, (env) => run(env, undefined, true)));

// Complete example with error handling
Plop.prepare({
  cwd: process.cwd(),
  configPath: './plopfile.js'
}, async env => {
  try {
    const plopInstance = await Plop.execute(env, run);
    console.log('Plop execution completed successfully');
  } catch (error) {
    console.error('Plop execution failed:', error.message);
    process.exit(1);
  }
});

Liftoff Integration

Plop uses Liftoff for configuration file discovery and environment setup.

/**
 * Liftoff instance configured for plop
 * Handles plopfile discovery and environment preparation
 */
const Plop: Liftoff;

Configuration Properties:

interface LiftoffOptions {
  name: string;        // 'plop'
  extensions: object;  // JavaScript file variants from interpret
  v8flags: string[];   // V8 flags for Node.js
}

Usage Examples:

import { Plop } from "plop";

// Prepare plop environment
Plop.prepare({
  cwd: process.cwd(),
  configPath: '/path/to/plopfile.js',
  preload: ['ts-node/register'],
  completion: null
}, function(env) {
  // Environment is ready, execute plop
  Plop.execute(env, run);
});

Progress Indication

Visual progress feedback during generator execution.

/**
 * Ora spinner instance for showing progress during file operations
 */
const progressSpinner: ora.Ora;

Configuration:

interface ProgressSpinnerConfig {
  stream: NodeJS.WriteStream;  // stdout in test, stderr otherwise
  isEnabled: boolean;          // Disabled in test environment or with --no-progress
}

Environment Configuration

Liftoff Environment Object

The environment object passed to execution functions contains configuration paths and metadata (see LiftoffEnvironment type in main documentation).

Preparation Options

Configuration options for Plop.prepare() (see PrepareOptions type in main documentation).

Custom CLI Wrapper

Complete example of wrapping Plop in a custom CLI tool:

#!/usr/bin/env node
import path from "node:path";
import minimist from "minimist";
import { Plop, run } from "plop";
import { dirname } from "node:path";
import { fileURLToPath } from "node:url";

const args = process.argv.slice(2);
const argv = minimist(args);
const __dirname = dirname(fileURLToPath(import.meta.url));

Plop.prepare({
  cwd: argv.cwd,
  configPath: path.join(__dirname, 'plopfile.js'),
  preload: argv.preload || [],
  completion: argv.completion
}, env => Plop.execute(env, run));

Custom Destination Path

Override the destination path for generated files:

Plop.prepare({
  // config options
}, env => 
  Plop.execute(env, (env) => {
    const options = {
      ...env,
      dest: process.cwd() // Base destination on current directory
    }
    return run(options, undefined, true)
  })
)

Error Handling

Programmatic usage should handle these error scenarios:

Plopfile not found: env.configPath will be null
Generator execution errors: Thrown from run() function
Node-plop errors: Thrown during plop instance creation
Action failures: May cause process exit depending on configuration

Example Error Handling:

try {
  const plop = await run(env);
  console.log('Generation completed successfully');
} catch (error) {
  console.error('Generation failed:', error.message);
  process.exit(1);
}

Install with Tessl CLI