Plop Micro-generator Framework

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to `require()` an ESM-formatted `plopfile.mjs` or a `.js` file treated as ESM (due to `"type": "module"` in `package.json`).
  fix Ensure your `plopfile`'s module type matches its export statement. For CommonJS `plopfiles`, use `module.exports`. For ESM `plopfiles`, use `export default` and potentially specify a `.mjs` extension or set `"type": "module"` in your `package.json`.

• plop: command not found

  cause The `plop` executable is not in your system's PATH, either because it's not installed globally or `npx` isn't being used for a local installation.
  fix Install plop globally (`npm install -g plop`) or run it using `npx plop` when installed locally within a project (`npm install --save-dev plop`). Alternatively, add a script to `package.json` like `"gen": "plop"` and execute with `npm run gen`.

• TypeError: plop.setGenerator is not a function

  cause This typically happens if the function exported from `plopfile.js` does not correctly receive the `plop` object as its argument, or if the `plopfile` is malformed.
  fix Verify that your `plopfile` correctly exports a function that accepts `plop` as its first parameter: `export default function (plop) { /* ... */ }` (ESM) or `module.exports = function (plop) { /* ... */ }` (CommonJS).

Warnings

• breaking Plop v4.0.0 dropped support for older Node.js versions (12, 14, and 16). Projects using Plop must now run on Node.js v18 or newer.
  Fix: Upgrade your Node.js environment to version 18 or higher.
• breaking The way `plopfile.js` files are authored depends on your project's module system. Using `export default` requires an ESM context (`.mjs` file extension or `"type": "module"` in `package.json`), while CommonJS projects must use `module.exports`.
  Fix: Ensure your `plopfile.js` uses the correct export syntax for your project's module type. If you're in an ESM project, use `export default function (plop) { ... }`. For CommonJS, use `module.exports = function (plop) { ... }`.
• gotcha While Plop supports TypeScript configuration files (`plopfile.ts`), enabling this requires additional setup (e.g., `ts-node` or `tsx`) in your project for Node.js to execute them directly, or pre-compilation. Plop v4.0.2 introduced an `--init-ts` flag to help with this.
  Fix: For TypeScript `plopfile.ts`, install `ts-node` (`npm i -D ts-node`) or `tsx` and configure your `package.json` scripts, or use `npx plop --init-ts` to set up boilerplate.
• gotcha Plop relies heavily on Handlebars.js for templating. Incorrect Handlebars syntax, missing helpers, or malformed data context can lead to unexpected output or template errors.
  Fix: Refer to the Handlebars.js documentation for correct syntax. Ensure that the data passed to your templates (from prompts) matches what the templates expect.
• gotcha To run `plop` directly from the terminal without `npx`, it's recommended to install it globally. Otherwise, you must use `npx plop` or define a `package.json` script.
  Fix: For convenient global access: `npm install -g plop`. For project-specific access: `npx plop` or add a script to `package.json` like `"generate": "plop"` and run `npm run generate`.

Install

• npm install plop npm
• yarn add plop yarn
• pnpm add plop pnpm

Imports

• plopfile export
  wrong:

  module.exports = function (plop) { /* ... */ }

  correct:

  export default function (plop) { /* ... */ }

  Use `export default` for ESM modules (`.mjs` or `type: 'module'` in `package.json`).
• plopfile export (CommonJS)
  wrong:

  export default function (plop) { /* ... */ }

  correct:

  module.exports = function (plop) { /* ... */ }

  Use `module.exports` for CommonJS modules (`.cjs` or `type: 'commonjs'` in `package.json`).
• nodePlop
  wrong:

  const nodePlop = require('plop').nodePlop;

  correct:

  import { nodePlop } from 'plop';

  `nodePlop` is the programmatic API to run generators from Node.js code, allowing for more advanced integration and testing. It is ESM-first.
• PlopGeneratorConfig (Type)

  import type { PlopGeneratorConfig } from 'plop';

  Import the type for generator configurations when working with TypeScript.

Quickstart

This example demonstrates how to programmatically use `nodePlop` from the `plop` package to define and execute a generator, simulating user input for component creation. It sets up a basic `plopfile` to generate a React component, including a TypeScript file and an optional CSS module, then cleans up the temporary files.

import { nodePlop } from 'plop';
import path from 'path';
import fs from 'fs';

// A minimal plopfile content
const plopfileContent = `
export default function (plop) {
  plop.setGenerator('component', {
    description: 'Create a new React component',
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'Component name (e.g., Button):'
      },
      {
        type: 'confirm',
        name: 'hasStyle',
        message: 'Include a CSS module?'
      }
    ],
    actions: [
      {
        type: 'add',
        path: 'src/components/{{pascalCase name}}/{{pascalCase name}}.tsx',
        templateFile: 'plop-templates/component.tsx.hbs',
      },
      {
        type: 'add',
        path: 'src/components/{{pascalCase name}}/index.ts',
        template: 'export * from "./{{pascalCase name}}";'
      },
      {
        type: 'add',
        path: 'src/components/{{pascalCase name}}/{{pascalCase name}}.module.css',
        template: '.{{camelCase name}} {\n  /* styles */\n}',
        skip: (data) => !data.hasStyle ? 'Skipping style file' : undefined
      }
    ]
  });
};
`;

// Create a temporary plopfile for demonstration
const tempPlopfilePath = path.join(process.cwd(), 'temp-plopfile.mjs');
const templateDir = path.join(process.cwd(), 'plop-templates');
fs.mkdirSync(templateDir, { recursive: true });
fs.writeFileSync(path.join(templateDir, 'component.tsx.hbs'), `
import React from 'react';
{{#if hasStyle}}import styles from './{{pascalCase name}}.module.css';{{/if}}

interface {{pascalCase name}}Props {
  // Define props here
}

export const {{pascalCase name}}: React.FC<{{pascalCase name}}Props> = ({}) => {
  return (
    <div{{#if hasStyle}} className={styles.{{camelCase name}}}{{/if}}>
      Hello from {{pascalCase name}}!
    </div>
  );
};
`);
fs.writeFileSync(tempPlopfilePath, plopfileContent);

// Programmatically run a plop generator
async function runGenerator() {
  const plop = await nodePlop(tempPlopfilePath, { 
    cwd: process.cwd(), 
    dest: process.cwd() 
  });
  const generator = plop.getGenerator('component');

  // Simulate user input for component 'MyComponent' with styles
  const results = await generator.runActions({
    name: 'MyComponent',
    hasStyle: true
  });

  console.log('Generator results:', results);

  // Clean up temporary files
  fs.unlinkSync(tempPlopfilePath);
  fs.unlinkSync(path.join(templateDir, 'component.tsx.hbs'));
  fs.rmdirSync(templateDir);

  console.log('Generated files for MyComponent and cleaned up temporary files.');
}

runGenerator().catch(console.error);