Generators Overview

Azu CLI's generator system is one of its most powerful features, allowing you to rapidly scaffold components, models, services, and complete applications. This guide provides an overview of how generators work, the philosophy behind them, and how to use them effectively.

What Are Generators?

Generators are automated code creation tools that follow Azu's conventions and best practices. They create files, directories, and boilerplate code based on templates, saving you time and ensuring consistency across your application.

Generator Philosophy

Convention Over Configuration

Generators follow established patterns and naming conventions, so you don't have to make decisions about file organization, naming, or structure.

DRY (Don't Repeat Yourself)

Instead of writing boilerplate code repeatedly, generators create it for you with proper patterns and best practices built-in.

Test-Driven Development

All generators create corresponding test files, encouraging you to write tests alongside your application code.

Modular Architecture

Each generator creates focused, single-responsibility components that work together as part of a larger system.

Available Generators

Generator

Purpose

Files Created

Use Case

endpoint

HTTP request handlers

Endpoints, contracts, pages, templates

Web controllers, API endpoints

model

Database models

Model classes with validations

Data persistence layer

service

Business logic

Service classes

Domain logic, complex operations

middleware

HTTP middleware

Middleware classes

Cross-cutting concerns

contract

Request/response validation

Contract structs

Input validation, API contracts

page

HTML page components

Page classes, templates

View layer, HTML rendering

component

Live interactive components

Component classes

Real-time UI, dynamic interfaces

validator

Custom validation logic

Validator classes

Reusable validation rules

migration

Database migrations

Migration files

Database schema changes

scaffold

Complete CRUD resource

All of the above

Rapid prototyping

Generator Types

1. Structural Generators

Create the main building blocks of your application:

Model: Data layer with database persistence
Endpoint: HTTP request handling and routing
Service: Business logic encapsulation
Middleware: Request/response processing

2. Interface Generators

Create user-facing components:

Page: HTML rendering and templates
Component: Interactive, real-time UI elements
Contract: API input/output contracts

3. Utility Generators

Create supporting functionality:

Validator: Custom validation logic
Migration: Database schema management

4. Composite Generators

Create multiple related files:

Scaffold: Complete CRUD resource with all components

Generator Workflow

1. Planning Phase

Before running a generator, consider:

Component name (should be descriptive and follow conventions)
Attributes (for models, contracts, components)
Relationships (how it connects to other components)
Custom options (API-only, skip tests, etc.)

2. Generation Phase

# Basic syntax
azu generate <type> <name> [attributes] [options]

# Examples
azu generate model User name:string email:string
azu generate endpoint posts
azu generate service UserRegistration

3. Customization Phase

After generation:

Review generated files for accuracy
Customize business logic in services and endpoints
Add validations to models and contracts
Write tests for your specific use cases
Update routes if needed

4. Integration Phase

Connect components together
Update imports and dependencies
Run migrations for database changes
Test the complete feature

Common Generator Patterns

1. Resource-Based Generation

For typical CRUD resources:

# Generate everything for a blog post
azu generate scaffold Post title:string content:text published:boolean

# Or step by step
azu generate model Post title:string content:text published:boolean
azu generate migration create_posts_table title:string content:text published:boolean
azu generate endpoint posts

2. Service-Oriented Generation

For complex business logic:

# Generate the service
azu generate service UserRegistration

# Generate supporting models if needed
azu generate model User name:string email:string
azu generate validator EmailValidator type:email

3. API-First Generation

For API-only applications:

# Generate API endpoints without pages
azu generate endpoint api/v1/users --api

# Generate models for data
azu generate model User name:string email:string
azu generate service UserRegistration

4. Component-Based Generation

For interactive features:

# Generate real-time components
azu generate component Counter count:integer --websocket
azu generate component ChatMessage text:string user:string --events send,delete

Generator Options

Global Options

Available for all generators:

Option

Description

Default

--force

Overwrite existing files

false

--skip-tests

Don't generate test files

false

--help

Show generator help

Specific Options

Different generators have specialized options:

Endpoint Generator:

--api - Generate API-only (no pages/templates)
--actions <list> - Specify which CRUD actions

Model Generator:

--validations - Add common validations
--timestamps - Add created_at/updated_at
--uuid - Use UUID primary key

Component Generator:

--websocket - Enable real-time features
--events <list> - Custom event handlers

Naming Conventions

Component Names

PascalCase for class names: User, BlogPost, UserRegistration
snake_case for file names: user.cr, blog_post.cr, user_registration.cr
Pluralized for collections: users (endpoints), posts (tables)

File Organization

src/
├── models/user.cr              # User
├── endpoints/users/            # Users::*Endpoint
│   ├── index_endpoint.cr
│   └── show_endpoint.cr
├── services/user_registration_service.cr  # UserRegistrationService
├── contracts/users/            # Users::*Contract
│   └── create_contract.cr
└── pages/users/                # Users::*Page
    └── index_page.cr

Namespace Conventions

Endpoints: Users::IndexEndpoint
Contracts: Users::CreateContract
Pages: Users::IndexPage
Models: User (no namespace)
Services: UserRegistrationService
Components: CounterComponent

Template System

How Templates Work

Generators use ECR (Embedded Crystal) templates:

# Template: model.cr.ecr
class <%= class_name %> < CQL::Model
  db_table "<%= table_name %>"

<% attributes.each do |name, type| -%>
  field <%= name %> : <%= crystal_type(type) %>
<% end -%>

<% if validations? -%>
<% attributes.each do |name, type| -%>
  validate :<%= name %>, presence: true
<% end -%>
<% end -%>
end

Template Variables

Common variables available in templates:

Variable

Description

Example

class_name

PascalCase class name

User

file_name

snake_case file name

user

table_name

Database table name

users

namespace

Module namespace

Users

attributes

Hash of attributes

{"name" => "string"}

project_name

Current project name

my_blog

Custom Templates

You can override default templates:

Create template directory:

mkdir -p ~/.azu/templates/generators/model/

Create custom template:

# ~/.azu/templates/generators/model/model.cr.ecr
# Your custom model template

Use custom template:

azu generate model User --template custom

Generated File Structure

Complete Example

When you run azu generate scaffold Post title:string content:text, you get:

src/
├── models/
│   └── post.cr                 # Post model with validations
├── endpoints/posts/
│   ├── index_endpoint.cr       # GET /posts
│   ├── show_endpoint.cr        # GET /posts/:id
│   ├── new_endpoint.cr         # GET /posts/new
│   ├── create_endpoint.cr      # POST /posts
│   ├── edit_endpoint.cr        # GET /posts/:id/edit
│   ├── update_endpoint.cr      # PUT /posts/:id
│   └── destroy_endpoint.cr     # DELETE /posts/:id
├── contracts/posts/
│   ├── index_contract.cr       # Query parameters
│   ├── show_contract.cr        # Show parameters
│   ├── create_contract.cr      # Creation validation
│   └── update_contract.cr      # Update validation
└── pages/posts/
    ├── index_page.cr           # Posts listing
    ├── show_page.cr            # Post details
    ├── new_page.cr             # New post form
    └── edit_page.cr            # Edit post form

public/templates/posts/
├── index_page.jinja            # HTML templates
├── show_page.jinja
├── new_page.jinja
└── edit_page.jinja

spec/
├── models/post_spec.cr         # Model tests
└── endpoints/posts_spec.cr     # Endpoint tests

db/migrations/
└── 20231214_120000_create_posts_table.cr  # Migration

Best Practices

1. Planning Before Generation

Design your models first to understand relationships
Plan your API structure before generating endpoints
Consider reusable components for common functionality

2. Consistent Naming

Use descriptive names that clearly indicate purpose
Follow Crystal conventions for naming
Be consistent across your application

3. Incremental Generation

Start with models to establish your data layer
Add services for business logic
Generate endpoints for HTTP interface
Use scaffold only for rapid prototyping

4. Customization After Generation

Review all generated code before committing
Add custom validation rules to models
Implement business logic in services
Customize templates to match your UI needs

5. Testing Strategy

Don't skip test generation unless absolutely necessary
Customize generated tests for your specific requirements
Add integration tests for complete workflows
Test both success and failure scenarios

Advanced Usage

1. Batch Generation

# Generate related components in sequence
azu generate model User name:string email:string
azu generate service UserRegistration
azu generate endpoint users
azu generate migration create_users_table name:string email:string

2. Template Customization

# Override specific generator templates
mkdir -p ~/.azu/templates/generators/model/
cp default_template.cr.ecr ~/.azu/templates/generators/model/model.cr.ecr
# Edit the template

3. Generator Configuration

# .azu/config.yml
generators:
  model:
    include_timestamps: true
    default_validations: true
  endpoint:
    default_format: json
    include_authentication: true

Troubleshooting

Common Issues

File Already Exists

# Use --force to overwrite
azu generate model User --force

Invalid Attribute Format

# Correct: name:type
azu generate model User name:string email:string

# Incorrect: name=string, name string

Missing Dependencies

# Ensure you're in an Azu project directory
# Check that required shards are installed
shards install

Generator Not Found

# Check available generators
azu generate --help

# Use full generator names, not abbreviations

Getting Help

# General generator help
azu generate --help

# Specific generator help
azu generate model --help
azu generate endpoint --help

The generator system is designed to accelerate your development while maintaining code quality and consistency. Master these tools to become highly productive with Azu applications.

Next Steps:

Endpoint Generator - Generate HTTP request handlers
Model Generator - Create database models
Development Workflows - Use generators in real projects

README Generator

The README Generator creates comprehensive, well-structured README.md files following modern documentation best practices for Crystal projects.

Overview

The README generator produces professional README.md files that include:

Project metadata: title, description, badges, license information
Installation instructions: both shards and manual installation
Usage examples: tailored to project type (library, CLI, web, service)
Development setup: prerequisites, setup steps, testing, building
Contribution guidelines: standards, workflow, issue reporting
Comprehensive sections: API docs, changelog, roadmap, support

Usage

Basic Usage

Generate a basic README.md file:

azu generate readme my_project

This creates a README.md file in the current directory with:

Project title: "My Project" (formatted)
Default description: "A Crystal project"
Standard sections for a library project
MIT license and basic author info
Default features and badges

Advanced Usage

Generate with custom configuration:

azu generate readme my_awesome_cli \
  --description "A powerful CLI tool for developers" \
  --github-user "johndoe" \
  --project-type "cli" \
  --license "Apache-2.0" \
  --database "postgresql" \
  --crystal-version ">= 1.15.0" \
  --output-dir "."

Project Type Specific Generation

Generate README tailored to specific project types:

# For CLI tools
azu generate readme my_tool --project-type cli

# For web applications
azu generate readme my_webapp --project-type web

# For libraries (default)
azu generate readme my_lib --project-type library

# For services/APIs
azu generate readme my_api --project-type service

Programmatic Usage

require "azu_cli/generators/readme_generator"

# Basic usage
generator = AzuCLI::Generators::ReadmeGenerator.new("my_project")
generator.generate!

# Advanced configuration
generator = AzuCLI::Generators::ReadmeGenerator.new(
  "my_awesome_project",
  output_dir: "/path/to/project",
  description: "An amazing Crystal project that does awesome things",
  github_user: "developer",
  license: "MIT",
  crystal_version: ">= 1.16.0",
  authors: ["Developer <dev@example.com>"],
  features: [
    "🚀 Lightning fast performance",
    "📦 Easy installation and setup",
    "🔧 Comprehensive test coverage",
    "💎 Built with Crystal",
    "🛡️ Type-safe and reliable"
  ],
  project_type: "web",
  database: "postgresql",
  has_badges: true,
  has_api_docs: true,
  has_roadmap: true,
  roadmap_items: [
    "Add GraphQL support",
    "Implement real-time features",
    "Performance optimizations"
  ],
  has_acknowledgments: true,
  acknowledgments: [
    "Crystal programming language community",
    "Contributors and maintainers"
  ]
)

output_path = generator.generate!

Generated Output

Example README.md

Generated for a web application with PostgreSQL:

# My Awesome Project

An amazing Crystal project that does awesome things

## Badges

[![Crystal CI](https://github.com/developer/my-awesome-project/actions/workflows/ci.yml/badge.svg)](https://github.com/developer/my-awesome-project/actions/workflows/ci.yml)
[![GitHub release](https://img.shields.io/github/release/developer/my-awesome-project.svg)](https://github.com/developer/my-awesome-project/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/developer/my-awesome-project/blob/master/LICENSE)

## Features

- 🚀 Lightning fast performance
- 📦 Easy installation and setup
- 🔧 Comprehensive test coverage
- 💎 Built with Crystal
- 🛡️ Type-safe and reliable

## Installation

### Using Shards

Add this to your application's `shard.yml`:

```yaml
dependencies:
  my_awesome_project:
    github: developer/my-awesome-project
```

Web Application

Start the server:
```
crystal run src/my_awesome_project.cr
```
Open your browser and visit:
```
http://localhost:3000
```

Configuration

Create a .env file in the project root:

# Database configuration
DATABASE_URL=postgres://user:password@localhost:5432/database_name

# Server configuration
PORT=3000
HOST=localhost

# Environment
ENVIRONMENT=development

Development

Prerequisites

Crystal >= 1.16.0
PostgreSQL database

Setup

Fork it (https://github.com/developer/my-awesome-project/fork)
Clone your fork...
Install dependencies...
Set up the database...

Contributing

Fork it
Create your feature branch
Make your changes and add tests
Ensure all tests pass
Format your code
Run the linter
Commit your changes
Push to the branch
Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.


## Configuration Options

### Project Metadata

| Option          | Type          | Default                          | Description                                  |
| --------------- | ------------- | -------------------------------- | -------------------------------------------- |
| `project_name`  | String        | Required                         | Project name (formatted automatically)      |
| `description`   | String        | `"A Crystal project"`            | Project description                          |
| `github_user`   | String        | `"your-github-user"`             | GitHub username/organization                 |
| `license`       | String        | `"MIT"`                          | License identifier                           |
| `authors`       | Array(String) | `["Your Name <your@email.com>"]` | Author information                           |

### Project Configuration

| Option             | Type   | Default        | Description                                                           |
| ------------------ | ------ | -------------- | --------------------------------------------------------------------- |
| `project_type`     | String | `"library"`    | Project type (`library`, `cli`, `web`, `service`)                    |
| `crystal_version`  | String | `">= 1.16.0"`  | Minimum Crystal version requirement                                   |
| `database`         | String | `"none"`       | Database type (`postgresql`, `mysql`, `sqlite`, `none`)              |

### Features and Content

| Option            | Type          | Default         | Description                      |
| ----------------- | ------------- | --------------- | -------------------------------- |
| `features`        | Array(String) | Default set     | List of project features         |
| `has_badges`      | Bool          | `true`          | Include GitHub badges            |
| `has_api_docs`    | Bool          | `true`          | Include API documentation section |
| `has_roadmap`     | Bool          | `false`         | Include roadmap section          |
| `roadmap_items`   | Array(String) | `[]`            | Roadmap items list               |

## Project Types

The generator tailors content based on project type:

### Library Projects (`library`)
- Installation via shards
- Basic and advanced usage examples
- API documentation links
- Library-specific development setup

### CLI Tools (`cli`)
- Command-line usage examples
- Available commands section
- Installation instructions
- CLI-specific help and options

### Web Applications (`web`)
- Server setup and configuration
- Database setup instructions
- Environment configuration
- Development server commands

### Services/APIs (`service`)
- API endpoint documentation
- Service configuration
- Deployment considerations
- Monitoring and health checks

## Naming Conventions

The generator automatically formats project names:

### Project Name Formatting

- Input: `my_awesome_project` → Title: "My Awesome Project"
- Input: `MyAwesomeProject` → Title: "My Awesome Project"
- Input: `my-awesome-project` → Title: "My Awesome Project"
- Input: `myproject` → Title: "Myproject"

### File and URL Generation

```yaml
Project: "my_awesome_project"
├── README title: "My Awesome Project"
├── GitHub repo: "my-awesome-project" (kebab-case)
├── Shard name: "my_awesome_project" (snake_case)
└── Class name: "MyAwesomeProject" (PascalCase)

Database Integration

When database support is specified, the README includes:

PostgreSQL

Database setup instructions
Connection configuration
Migration commands
Prerequisites section mentions PostgreSQL

MySQL

MySQL-specific setup
Connection string examples
Database creation steps

SQLite

File-based database info
Simplified setup process
Local development focus

None

Omits database-related sections
Focuses on application logic
Simplified prerequisites

Advanced Features

Badges and Shields

Automatically includes relevant badges:

CI/CD Status: GitHub Actions workflow status
Release Version: Latest GitHub release version
License: License type with appropriate color
Custom badges: Can be extended for specific needs

Author Attribution

Generates GitHub links for authors:

Extracts names from email format: "John Doe <john@example.com>"
Creates GitHub profile links: https://github.com/john-doe
Assigns roles: first author is "creator and maintainer", others are "contributors"

Roadmap Integration

When enabled, includes:

Checkbox-style roadmap items
Future feature planning
Development priorities
Community engagement

Support Information

Customizable support section:

Default: generic contribution encouragement
Custom: specific support channels, contact info
Community resources and links

Validation

The generator validates:

Project names: Must be valid Crystal identifiers
GitHub usernames: Must follow GitHub username format
Required fields: Description, license, crystal version cannot be empty
Author format: Authors array cannot be empty
Features: Feature descriptions cannot be empty

Integration with Azu CLI

The README generator integrates with the main azu generate command:

# List available generators
azu generate --help

# Generate README
azu generate readme my_project

# Generate with specific options
azu generate readme my_project \
  --description "My project description" \
  --project-type web \
  --github-user myusername

Best Practices

Content Guidelines

Write clear, concise descriptions
Include comprehensive installation instructions
Provide working code examples
Document all configuration options
Keep README updated with project changes

Project Type Selection

Library: Choose for reusable packages and modules
CLI: Choose for command-line tools and utilities
Web: Choose for web applications and websites
Service: Choose for APIs and microservices

GitHub Integration

Use your actual GitHub username
Ensure repository names match project names
Set up CI/CD workflows referenced in badges
Create LICENSE file to match specified license

Feature Description

Use emoji for visual appeal and scanning
Focus on user benefits, not technical details
Keep descriptions short and impactful
Highlight unique selling points

Database Documentation

Document all required environment variables
Provide working connection examples
Include database schema information
Document migration and seeding processes

Troubleshooting

Common Issues

Invalid GitHub username error:

Error: Invalid GitHub username format: -invalid-

Solution: Use valid GitHub username format (alphanumeric, hyphens allowed, cannot start/end with hyphen)

Empty description error:

Error: Description cannot be empty

Solution: Provide a meaningful project description

Unsupported project type:

Error: Unsupported project type: invalid

Solution: Use one of the supported types: library, cli, web, service

Debugging

Check generated content:

cat README.md

Validate Markdown syntax:

# Use a Markdown linter
markdownlint README.md

Preview rendered output:

# Use a Markdown viewer or GitHub preview

Examples

Minimal Library

generator = AzuCLI::Generators::ReadmeGenerator.new(
  "crypto_utils",
  description: "Cryptographic utilities for Crystal",
  github_user: "cryptodev"
)
generator.generate!

Full-Featured Web App

generator = AzuCLI::Generators::ReadmeGenerator.new(
  "social_platform",
  description: "A modern social media platform built with Crystal",
  github_user: "socialdev",
  project_type: "web",
  database: "postgresql",
  features: [
    "🔐 Secure authentication and authorization",
    "📱 Real-time messaging and notifications",
    "🎨 Modern, responsive UI design",
    "⚡ High-performance backend",
    "🛡️ Privacy-focused architecture"
  ],
  has_roadmap: true,
  roadmap_items: [
    "Mobile application development",
    "Advanced analytics dashboard",
    "Integration with external services",
    "Performance monitoring and optimization"
  ]
)
generator.generate!

CLI Tool

generator = AzuCLI::Generators::ReadmeGenerator.new(
  "file_organizer",
  description: "Intelligent file organization tool",
  github_user: "devtools",
  project_type: "cli",
  features: [
    "🗂️ Smart file categorization",
    "⚡ Lightning-fast processing",
    "🎯 Customizable organization rules",
    "📊 Detailed operation reports"
  ]
)
generator.generate!

PreviousCLI Options Reference NextEndpoint Generator

Last updated 2 months ago