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

Console Interface

Name: tessl/npm-plop
Author: tessl

Plop's console interface provides user interaction functions for displaying help, selecting generators, initializing plopfiles, and showing visual feedback during operations.

Capabilities

Generator Selection

Interactive generator selection when multiple generators are available.

/**
 * Display generator selection list to user
 * @param plopList - Array of available generators with name and description
 * @param message - Optional custom selection message
 * @returns Promise resolving to selected generator name
 */
async function chooseOptionFromList(plopList, message);

Generator List Format:

interface GeneratorInfo {
  name: string;           // Generator name
  description?: string;   // Optional description
}

Usage Examples:

import { chooseOptionFromList } from "plop/src/console-out.js";

const generators = [
  { name: "component", description: "React component generator" },
  { name: "page", description: "Next.js page generator" }
];

const selectedGenerator = await chooseOptionFromList(
  generators,
  "Please choose a generator:"
);

Help System

Display comprehensive help information for users.

/**
 * Display help screen with usage information and available options
 */
function displayHelpScreen();

The help screen includes:

Usage examples for different command patterns
Complete list of CLI options and flags
Examples of bypass argument usage
Advanced options for power users

Generator Help

Show specific help for individual generators.

/**
 * Display help message for a specific generator showing available prompts
 * @param generator - Generator object with prompts configuration
 */
function getHelpMessage(generator);

Generator Format:

interface Generator {
  prompts: Prompt[];      // Array of inquirer prompts
  name: string;           // Generator name
  description?: string;   // Generator description
}

interface Prompt {
  name: string;           // Prompt name for CLI arguments
  message: string;        // Prompt message text
  help?: string;          // Optional help text
  type: string;           // Inquirer prompt type
}

Plopfile Initialization

Create initial plopfile configurations for new projects.

/**
 * Create initial plopfile.js or plopfile.ts in current directory
 * @param force - Overwrite existing plopfile if present (default: false)
 * @param useTypescript - Generate TypeScript plopfile (default: false)
 * @throws Error if plopfile exists and force is false
 */
function createInitPlopfile(force, useTypescript);

Generated JavaScript Plopfile:

export default function (plop) {
  plop.setGenerator('basics', {
    description: 'this is a skeleton plopfile',
    prompts: [],
    actions: []
  });
}

Generated TypeScript Plopfile:

import type { NodePlopAPI } from 'plop'

export default async function (plop: NodePlopAPI) {

}

Usage Examples:

import { createInitPlopfile } from "plop/src/console-out.js";

// Create basic JavaScript plopfile
createInitPlopfile(false, false);

// Create TypeScript plopfile, overwriting existing
createInitPlopfile(true, true);

Action Type Display

Visual mapping of action types to console symbols for better user experience.

/**
 * Map action type names to display symbols or full names
 * @param name - Action type name (add, modify, append, etc.)
 * @param noMap - Show full type name instead of symbol
 * @returns Formatted display string for action type
 */
function typeMap(name, noMap);

Type Display Mapping:

interface TypeDisplayMapping {
  function: string;    // "->" (yellow)
  add: string;         // "++" (green)
  addMany: string;     // "+!" (green)
  modify: string;      // "+-" (green/red)
  append: string;      // "_+" (green)
  skip: string;        // "--" (green)
}

Usage Examples:

import { typeMap } from "plop/src/console-out.js";

console.log(typeMap("add", false));     // "++ " (with green color)
console.log(typeMap("add", true));      // "add" (dimmed)
console.log(typeMap("modify", false));  // "+-" (green/red)

Input Processing

Bypass Data Processing

Process and validate bypass arguments for generators.

/**
 * Combine different types of bypass data for generator prompts
 * @param generator - Generator object with prompts configuration
 * @param bypassArr - Array of positional bypass arguments
 * @param plopArgV - Named arguments from CLI (--name=value format)
 * @returns Array of processed bypass values
 */
function combineBypassData(generator, bypassArr, plopArgV);

Processing Rules:

Validates named arguments against prompt names
Merges positional and named bypass arguments
Converts undefined values to "_" placeholders
Throws errors for invalid arguments or too many values

Usage Examples:

import { combineBypassData } from "plop/src/bypass.js";

const generator = {
  name: "component",
  prompts: [
    { name: "name", type: "input" },
    { name: "type", type: "list" }
  ]
};

// Positional arguments
const bypass1 = combineBypassData(generator, ["MyComponent", "react"], {});
// Result: ["MyComponent", "react"]

// Named arguments
const bypass2 = combineBypassData(generator, [], { name: "MyComponent", type: "react" });
// Result: ["MyComponent", "react"]

// Mixed arguments
const bypass3 = combineBypassData(generator, ["MyComponent"], { type: "react" });
// Result: ["MyComponent", "react"]

Console Styling

Plop uses chalk for colored console output:

Green: Successful operations, added files
Red: Errors, failed operations
Yellow: Warnings, function indicators
Blue: Information messages, plop branding
Gray/Dim: Secondary information, help text

Error Messages

Standard error message formats:

const ERROR_FORMATS = {
  noPlopfile: "[PLOP] No plopfile found",
  noGenerators: "[PLOP] No generator found in plopfile",
  generatorNotFound: '[PLOP] Could not find a generator for "{name}"',
  tooManyArgs: '[PLOP] Too many bypass arguments passed for "{generator}"',
  invalidArg: '[PLOP] "{arg}" is an invalid argument for "{generator}"',
  readError: "[PLOP] Something went wrong with reading your plop file",
  initExists: '"{filename}" already exists at this location.'
};

Install with Tessl CLI