Getting Started

Installation

Clay is a globally installed command-line tool. Install it using npm:

npm install -g clay-generator

Verify the installation by running:

clay --version

Prerequisites

• Node.js 14 or higher
• npm 7 or higher
• Basic understanding of JSON
• Familiarity with Handlebars templates (helpful but not required)

Quick Start

1. Initialize a Project

Navigate to your project directory and initialize Clay:

cd my-project
clay init

This creates a .clay file that tracks all generated files.

2. Create a Model

Create a directory for your Clay configuration and model:

mkdir -p clay
cat > clay/model.json << 'EOF'
{
  "name": "user-service",
  "generators": ["./generators/api"],
  "model": {
    "types": [
      {
        "name": "User",
        "fields": [
          { "name": "id", "type": "string" },
          { "name": "email", "type": "string" },
          { "name": "name", "type": "string" }
        ]
      }
    ]
  }
}
EOF

3. Create a Generator

Create a simple generator that creates a model file:

mkdir -p clay/generators/api/templates
cat > clay/generators/api/generator.json << 'EOF'
{
  "partials": [],
  "steps": [
    {
      "generate": "templates/{{name}}.model.js",
      "select": "$.model.types[*]",
      "target": "src/models/"
    }
  ],
  "formatters": []
}
EOF

4. Create a Template

Create a Handlebars template for the generated files. The template's filename becomes the output filename (rendered as Handlebars), so name it {{name}}.model.js — each selected type writes its own file (e.g. src/models/User.model.js):

cat > "clay/generators/api/templates/{{name}}.model.js" << 'EOF'
// Generated Model: {{name}}

class {{pascalCase name}} {
  constructor(data) {
{{#each fields}}
    this.{{name}} = data.{{name}};
{{/each}}
  }

  toJSON() {
    return {
{{#each fields}}
      {{name}}: this.{{name}},
{{/each}}
    };
  }
}

module.exports = {{pascalCase name}};
EOF

5. Generate Code

Now generate your code:

clay generate clay/model.json ./

Or, since you have a .clay file, you can simply run:

clay generate

This creates src/models/user.model.js based on your model!

Project Structure

A typical Clay project looks like this:

.
├── .clay                      # Tracks generated files
├── clay/                      # Clay configuration
│   ├── model.json            # Your domain model
│   └── generators/           # Custom generators
│       └── api/
│           ├── generator.json
│           └── templates/
│               └── model.js
└── src/                      # Generated code appears here
    └── models/
        └── user.model.js

Basic Commands

Generate

Generate code from your model. Also removes obsolete non-touch files tracked in .clay for models that ran (e.g. after you delete an entity and regenerate):

clay generate <model_path> <output_path>
clay generate  # Uses .clay file

Clean

Full wipe of tracked generated files. Not required for ordinary model shrink — use generate for that. Prefer clean when renaming output paths or starting over:

clay clean <model_path> <output_path>
clay clean  # Uses .clay file

Watch

Automatically regenerate when files change:

clay watch <model_path> <output_path>
clay watch  # Uses .clay file

Test Path

Test JSONPath expressions against your model:

clay test-path <model_path> "$.model.types[*].fields[*]"

Next Steps

• Learn about Models - Structure your domain models
• Learn about Generators - Configure generation steps
• Learn about Templates - Write Handlebars templates
• CLI Reference - Complete command reference