Generators

What are Generators?

Generators define a sequence of steps that transform your model into code. Each generator contains templates, partials, and configuration that tells Clay exactly what to generate.

Generator Structure

{
  "partials": ["partials/header.hbs"],
  "steps": [
    {
      "generate": "templates/model.js",
      "select": "$.model.types[*]",
      "target": "src/models/{{kebabCase name}}.js"
    }
  ],
  "formatters": ["clay-generator-formatter-prettier"]
}

Generator Properties

partials

Array of Handlebars partial files to include:

"partials": [
  "partials/header.hbs",
  "partials/footer.hbs"
]

steps

Array of generation steps (run in order):

"steps": [
  { "runCommand": "mkdir -p src/models" },
  { "generate": "templates/model.js", "select": "$.model.types[*]" },
  { "copy": "foundation", "target": "src/foundation" }
]

formatters

Optional formatters to prettify generated code:

"formatters": ["clay-generator-formatter-prettier"]

Step Types

1. Generate (Template)

Generate files from Handlebars templates:

{
  "generate": "templates/model.js",
  "select": "$.model.types[*]",
  "target": "src/models/{{kebabCase name}}.model.js",
  "touch": false
}

Parameters:

• generate - Path to template file
• select - JSONPath to select data (optional)
• target - Output path (can use Handlebars)
• touch - If true, only generate if file doesn't exist

2. Copy

Copy files or directories:

{
  "copy": "foundation",
  "select": "$.model.types[*]",
  "target": "src/{{kebabCase name}}/foundation"
}

Parameters:

• copy - Source path or git repo (e.g., "git+user/repo")
• select - JSONPath to iterate (optional)
• target - Destination path (can use Handlebars)

3. Run Command

Execute shell commands:

{
  "runCommand": "npm install",
  "npxCommand": false
}

With model data:

{
  "runCommand": "echo Generating {{name}}",
  "select": "$.model.types[*]"
}

Parameters:

• runCommand - Shell command to execute
• npxCommand - If true, run with npx
• select - JSONPath to iterate (optional)

Complete Example

{
  "partials": [
    "partials/license-header.hbs",
    "partials/imports.hbs"
  ],
  "steps": [
    {
      "runCommand": "mkdir -p src/models src/controllers src/routes"
    },
    {
      "generate": "templates/model.js",
      "select": "$.model.types[*]",
      "target": "src/models/{{kebabCase name}}.model.js"
    },
    {
      "generate": "templates/controller.js",
      "select": "$.model.types[*]",
      "target": "src/controllers/{{kebabCase name}}.controller.js"
    },
    {
      "generate": "templates/routes.js",
      "select": "$.model.types[*]",
      "target": "src/routes/{{kebabCase name}}.routes.js"
    },
    {
      "generate": "templates/index.js",
      "target": "src/index.js",
      "touch": true
    },
    {
      "copy": "config",
      "target": "config"
    },
    {
      "runCommand": "npm install"
    }
  ],
  "formatters": ["clay-generator-formatter-prettier"]
}

Creating a Generator

Initialize

clay init generator my-generator

This creates:

clay/generators/my-generator/
├── generator.json
└── templates/

Directory Structure

clay/generators/api/
├── generator.json          # Configuration
├── templates/              # Handlebars templates
│   ├── model.js
│   ├── controller.js
│   └── routes.js
├── partials/              # Reusable template parts
│   ├── header.hbs
│   └── imports.hbs
└── foundation/            # Files to copy
    └── config.js

Best Practices

• Order steps logically (create directories before files)
• Use select to iterate over model arrays
• Use touch: true for files users might customize
• Test JSONPath selectors with clay test-path
• Use partials for license headers, imports, etc.
• Add formatters for consistent code style
• Keep templates focused on single responsibilities

Getting Generators

Clay uses a local-first approach. All generators are stored in your project's clay/generators/ directory.

Create a New Generator

Start from scratch with a template:

clay init generator my-api-generator

Copy from a Local Path

Copy a generator from another location on your machine:

clay generator add /path/to/my-generator
clay generator add ../other-project/generators/my-generator

Clone from the Registry

Browse available generators and clone them to your project:

clay generator list-available
clay generator add clay-model-documentation

Clone from GitHub

Clone any generator repository. It will be copied to your local clay/generators/ directory:

clay generator add https://github.com/user/my-generator

Reference in Your Model

Generators are referenced by their path to the generator.json file:

{
  "name": "my-app",
  "generators": [
    "generators/my-api-generator/generator.json",
    "generators/forms/generator.json"
  ],
  "model": {...}
}

Sharing Generators

Since generators are stored locally in your project, sharing them is easy:

• Commit to version control - Your clay/generators/ directory is part of your project
• Copy between projects - Simply copy the generator directory
• Share via GitHub - Create a repo with your generator and others can clone it
• Add to the registry - Submit a PR to add your generator to the discovery registry