azu generate

The azu generate command is one of the most powerful features of Azu CLI. It creates various components for your application, following Azu conventions and best practices. This command helps you rapidly develop applications by generating boilerplate code, tests, and associated files.

Overview

azu generate <generator_type> <name> [attributes] [options]

Available Generators

Generator

Alias

Description

endpoint

e, controller

HTTP endpoints with full CRUD operations

model

m

CQL ORM models with validations

service

s

Business logic services following DDD patterns

middleware

mw

HTTP middleware components

contract

c

Request/response validation contracts

page

p

Page components for rendering HTML

component

comp

Live interactive components with real-time features

validator

v, val

Custom validation logic

migration

mig

Database migration files

scaffold

Complete CRUD resource (all of the above)

Global Options

Option

Description

Default

--force

Overwrite existing files without prompting

false

--skip-tests

Don't generate test files

false

--skip-routes

Don't register routes automatically

false

--help

Show help for the generator

Endpoint Generator

Generates HTTP endpoints (controllers) for handling web requests.

Usage

azu generate endpoint <name> [actions] [options]

Examples

# Generate basic endpoint with all CRUD actions
azu generate endpoint users

# Generate endpoint with specific actions
azu generate endpoint posts index show create

# Generate API endpoint
azu generate endpoint api/v1/posts --api

# Skip test generation
azu generate endpoint users --skip-tests

Generated Files

src/endpoints/users/
├── index_endpoint.cr      # GET /users
├── show_endpoint.cr       # GET /users/:id
├── new_endpoint.cr        # GET /users/new
├── create_endpoint.cr     # POST /users
├── edit_endpoint.cr       # GET /users/:id/edit
├── update_endpoint.cr     # PUT/PATCH /users/:id
└── destroy_endpoint.cr    # DELETE /users/:id

src/contracts/users/
├── index_contract.cr
├── show_contract.cr
├── create_contract.cr
└── update_contract.cr

src/pages/users/
├── index_page.cr
├── show_page.cr
├── new_page.cr
└── edit_page.cr

public/templates/users/
├── index_page.jinja
├── show_page.jinja
├── new_page.jinja
└── edit_page.jinja

spec/endpoints/users_spec.cr

Example Generated Endpoint

# src/endpoints/users/index_endpoint.cr
class Users::IndexEndpoint
  include Azu::Endpoint

  def call(request)
    users = User.all
    contract = Users::IndexContract.new(request)

    if contract.valid?
      index_page = Users::IndexPage.new(users: users)
      index_page.render
    else
      render_errors(contract.errors)
    end
  end
end

Options

Option

Description

--api

Generate API-only endpoints (no pages/templates)

--actions <list>

Specify which actions to generate

Model Generator

Generates CQL ORM models with validations and relationships.

Usage

azu generate model <name> [field:type] [options]

Examples

# Basic model
azu generate model User

# Model with attributes
azu generate model User name:string email:string age:integer

# Model with different field types
azu generate model Post title:string content:text published:boolean author_id:integer

# Model with validations
azu generate model User name:string email:string --validations

Field Types

Type

Crystal Type

Database Type

string

String

VARCHAR/TEXT

text

String

TEXT

integer

Int32

INTEGER

bigint

Int64

BIGINT

float

Float64

FLOAT

decimal

BigDecimal

DECIMAL

boolean

Bool

BOOLEAN

date

Date

DATE

time

Time

TIMESTAMP

json

JSON::Any

JSON/JSONB

uuid

UUID

UUID

Generated Files

src/models/user.cr
spec/models/user_spec.cr

Example Generated Model

# src/models/user.cr
require "cql"

class User < CQL::Model
  db_table "users"

  field id : Int64, primary: true, auto_increment: true
  field name : String
  field email : String
  field age : Int32?
  field created_at : Time = Time.utc
  field updated_at : Time = Time.utc

  validate :name, presence: true, length: {min: 2, max: 50}
  validate :email, presence: true, format: EMAIL_REGEX, uniqueness: true
  validate :age, numericality: {greater_than: 0, less_than: 150}

  before_save :update_timestamps

  private def update_timestamps
    self.updated_at = Time.utc
  end
end

Options

Option

Description

--validations

Add common validations

--timestamps

Add created_at/updated_at fields

--uuid

Use UUID as primary key

Service Generator

Generates service classes for encapsulating business logic.

Usage

azu generate service <name> [methods] [options]

Examples

# Basic service
azu generate service UserRegistration

# Service with specific methods
azu generate service EmailNotification send deliver

# Service with dependencies
azu generate service PaymentProcessor --dependencies user_repo,payment_gateway

Generated Files

src/services/user_registration_service.cr
spec/services/user_registration_service_spec.cr

Example Generated Service

# src/services/user_registration_service.cr
class UserRegistrationService
  def initialize(@email : String, @password : String)
  end

  def call
    return failure("Email already exists") if User.exists?(email: @email)

    user = User.create!(
      email: @email,
      password: hash_password(@password)
    )

    EmailService.send_welcome_email(user)
    success(user)
  rescue ex
    failure("Registration failed: #{ex.message}")
  end

  private def hash_password(password)
    # Password hashing logic
  end

  private def success(data)
    {success: true, data: data}
  end

  private def failure(message)
    {success: false, error: message}
  end
end

Component Generator

Generates live, interactive components for real-time features.

Usage

azu generate component <name> [attributes] [options]

Examples

# Basic component
azu generate component Counter

# Component with attributes
azu generate component Counter count:integer step:integer

# Real-time component with WebSocket
azu generate component ChatMessage --websocket

# Component with events
azu generate component TodoItem completed:boolean --events toggle,delete

Generated Files

src/components/counter_component.cr
spec/components/counter_component_spec.cr

Example Generated Component

# src/components/counter_component.cr
class CounterComponent
  include Azu::Component

  def initialize(@count : Int32 = 0, @step : Int32 = 1)
  end

  def increment
    @count += @step
    update_element("counter-value", @count.to_s)
    broadcast_update({
      type: "counter_updated",
      count: @count,
      timestamp: Time.utc
    })
  end

  def decrement
    @count -= @step
    update_element("counter-value", @count.to_s)
    broadcast_update({
      type: "counter_updated",
      count: @count,
      timestamp: Time.utc
    })
  end

  def reset
    @count = 0
    update_element("counter-value", "0")
    broadcast_update({
      type: "counter_reset",
      timestamp: Time.utc
    })
  end

  def render
    <<-HTML
    <div id="counter-component" class="counter">
      <h3>Counter Component</h3>
      <div class="counter-display">
        <span id="counter-value">#{@count}</span>
      </div>
      <div class="counter-controls">
        <button onclick="counter.decrement()">-</button>
        <button onclick="counter.reset()">Reset</button>
        <button onclick="counter.increment()">+</button>
      </div>
    </div>
    HTML
  end
end

Options

Option

Description

--websocket

Enable WebSocket support for real-time updates

--events <list>

Specify custom event handlers

Migration Generator

Generates database migration files.

Usage

azu generate migration <name> [field:type] [options]

Examples

# Create table migration
azu generate migration create_users_table name:string email:string

# Add column migration
azu generate migration add_age_to_users age:integer

# Remove column migration
azu generate migration remove_age_from_users age:integer

# Add index migration
azu generate migration add_index_to_users_email --index email

Generated Files

db/migrations/20231214_120000_create_users_table.cr

Example Generated Migration

# db/migrations/20231214_120000_create_users_table.cr
class CreateUsersTable < CQL::Migration
  def up
    create_table "users" do |t|
      t.string "name", null: false
      t.string "email", null: false
      t.integer "age"
      t.timestamps
    end

    add_index "users", "email", unique: true
  end

  def down
    drop_table "users"
  end
end

Migration Types

Based on the migration name, different templates are used:

create_*_table - Creates a new table
add_*_to_* - Adds columns to existing table
remove_*_from_* - Removes columns from table
add_index_* - Adds database index

Scaffold Generator

Generates a complete CRUD resource with all associated files.

Usage

azu generate scaffold <name> [field:type] [options]

Examples

# Complete blog post resource
azu generate scaffold Post title:string content:text published:boolean

# User resource with validations
azu generate scaffold User name:string email:string --validations

# API-only scaffold
azu generate scaffold Product name:string price:decimal --api

Generated Files

The scaffold generator creates:

Model with validations
All CRUD endpoints
Request contracts
Page components
HTML templates
Test files
Database migration

src/models/post.cr
src/endpoints/posts/*.cr (7 files)
src/contracts/posts/*.cr (4 files)
src/pages/posts/*.cr (4 files)
public/templates/posts/*.jinja (4 files)
spec/models/post_spec.cr
spec/endpoints/posts_spec.cr
db/migrations/*_create_posts_table.cr

Advanced Usage

Custom Templates

You can create custom generator templates:

# Create custom template directory
mkdir -p ~/.azu/templates/generators/my_generator

# Create template files
echo "Custom template content" > ~/.azu/templates/generators/my_generator/file.cr.ecr

Generator Hooks

Add custom logic before/after generation:

# config/generators.cr
Azu::Generators.configure do |config|
  config.before_generate do |generator, options|
    puts "Generating #{generator.name}..."
  end

  config.after_generate do |generator, files|
    puts "Generated #{files.size} files"
  end
end

Batch Generation

Generate multiple components at once:

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

# Or use scaffold for everything
azu generate scaffold User name:string email:string

Troubleshooting

Common Issues

File Already Exists

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

# Or remove existing files first
rm src/models/user.cr
azu generate model User

Invalid Attribute Syntax

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

# Not: name=string or name string

Generator Not Found

# Check available generators
azu generate --help

# Use correct generator name
azu generate endpoint users  # not controller

Best Practices

Use descriptive names for generators
Plan your attributes before generating
Generate tests alongside code
Use scaffold for rapid prototyping
Customize generated code to fit your needs

Related Documentation:

Generators Guide - Detailed generator documentation
Project Structure - Understanding generated files
Development Workflows - Using generators in development

Previousazu init Nextazu serve

Last updated 4 months ago