class AmberCLI::Documentation::ConfigurationReference

• AmberCLI::Documentation::ConfigurationReference
• Reference
• Object

Overview

Configuration Reference

Detailed reference for all configuration options and files.

Generator Configuration

Generator configurations define how code generation works:

Configuration Schema

name: string                    # Required: Generator name
description: string             # Optional: Description
template_variables:             # Optional: Default template variables
  key: value
naming_conventions:             # Optional: Word transformation rules
  snake_case: "underscore_format"
  pascal_case: "CamelCaseFormat"
file_generation_rules:          # Required: File generation rules
  generator_type:
    - template: "template_name"
      output_path: "path/{{variable}}.cr"
      transformations:          # Optional: Variable transformations
        custom_var: "{{name}}_custom"
      conditions:               # Optional: Generation conditions
        if_exists: "file.cr"
post_generation_commands:       # Optional: Commands to run after generation
  - "crystal tool format {{output_path}}"
dependencies:                   # Optional: Required dependencies
  - "some_shard"

Template Variables

Available template variables for file generation:

• {{name}} - Original name provided
• {{snake_case}} - Snake case transformation
• {{pascal_case}} - Pascal case transformation
• {{snake_case_plural}} - Plural snake case
• {{pascal_case_plural}} - Plural pascal case
• {{output_path}} - Generated file path

Custom variables can be defined in generator configuration.

Watch Configuration

Watch mode behavior is configurable in .amber.yml:

watch:
  run:                          # Development environment
    build_commands:             # Commands to build the application
      - "mkdir -p bin"
      - "crystal build ./src/app.cr -o bin/app"
    run_commands:               # Commands to run the application
      - "bin/app"
    include:                    # Files to watch for changes
      - "./config/**/*.cr"
      - "./src/**/*.cr"
      - "./src/views/**/*.slang"
  test:                         # Test environment (optional)
    build_commands:
      - "crystal spec"
    run_commands:
      - "echo 'Tests completed'"
    include:
      - "./spec/**/*.cr"

Configuration Reference

Amber CLI uses several configuration mechanisms to customize behavior for different project types and development workflows.

Project Configuration (.amber.yml)

The .amber.yml file in your project root configures project-specific settings:

database: pg                    # Database type: pg, mysql, sqlite
language: slang                 # Template language: slang, ecr
model: granite                  # ORM: granite, jennifer
watch:
  run:
    build_commands:
      - "crystal build ./src/my_app.cr -o bin/my_app"
    run_commands:
      - "bin/my_app"
    include:
      - "./config/**/*.cr"
      - "./src/**/*.cr"

Generator Configuration

Custom generators can be configured using JSON or YAML files in the generator_configs/ directory:

Basic Generator Configuration

name: "custom_model"
description: "Generate a custom model with validation"
template_directory: "templates/models"
amber_framework_version: "1.4.0"    # Amber framework version for new projects
custom_variables:
  author: "Your Name"
  license: "MIT"
naming_conventions:
  table_prefix: "app_"
file_generation_rules:
  - template_file: "model.cr.ecr"
    output_path: "src/models/{{snake_case}}.cr"
    transformations:
      class_name: "pascal_case"

Framework Version Configuration

The amber_framework_version setting determines which version of the Amber framework gets used when creating new applications. This is separate from the CLI tool version and allows you to:

• Pin projects to specific Amber versions
• Test with different framework versions
• Maintain compatibility with existing projects

Available template variables:

• {{cli_version}} - Current Amber CLI version
• {{amber_framework_version}} - Configured Amber framework version
• All word transformations (snake_case, pascal_case, etc.)

Advanced Generator Features

Conditional File Generation

file_generation_rules:
  - template_file: "api_spec.cr.ecr"
    output_path: "spec/{{snake_case}}_spec.cr"
    conditions:
      generate_specs: "true"

Custom Transformations

naming_conventions:
  namespace_prefix: "MyApp::"
  table_prefix: "my_app_"
transformations:
  full_class_name: "pascal_case"  # Will use namespace_prefix

Environment Configuration

Environment-specific settings go in config/environments/:

# config/environments/development.yml
database_url: "postgres://localhost/myapp_development"
amber_framework_version: "1.4.0"

# config/environments/production.yml
database_url: ENV["DATABASE_URL"]
amber_framework_version: "1.4.0"

Defined in:

amber_cli/documentation.cr