Configuration API

Reference for the ao.config.yml configuration file and its options.

Overview

The ao.config.yml file is the main configuration file for ao-forge projects. It defines project settings, AO processes, build options, and deployment configurations.

Configuration Schema

Basic Configuration

# Project information
name: 'my-ao-app'                    # Project name
version: '1.0.0'                     # Project version
description: 'My AO-powered application'  # Project description

# Framework configuration
framework: 'nextjs'                  # Framework: 'nextjs' or 'nuxtjs'
packageManager: 'pnpm'               # Package manager: 'npm', 'pnpm', or 'yarn'

# AO process configuration
luaFiles: ['counter.lua', 'token.lua']  # List of Lua files
autoStart: false                     # Auto-start AO processes
processName: 'my-process'            # Default process name

Development Configuration

# Development settings
ports:
  dev: 3000                          # Development server port
  ao: 8080                           # AO process port
  monitoring: 9090                   # Process monitoring port

# Development features
debug: false                         # Enable debug mode
hotReload: true                      # Enable hot reloading
sourceMaps: true                     # Generate source maps

Build Configuration

# Build settings
build:
  output: './dist'                   # Build output directory
  optimize: true                     # Enable optimization
  sourceMaps: false                  # Generate source maps
  minify: true                       # Minify assets
  compression: true                  # Enable compression
  
# Build optimization
optimization:
  treeshaking: true                  # Enable tree shaking
  codesplitting: true                # Enable code splitting
  deadCodeElimination: true          # Remove dead code
  constantFolding: true              # Optimize constants

Deployment Configuration

# Deployment settings
deploy:
  platform: 'vercel'                 # Deployment platform
  environment: 'production'          # Deployment environment
  domain: 'my-app.vercel.app'        # Deployment domain
  customDomain: 'my-app.com'         # Custom domain
  
# Platform-specific settings
vercel:
  projectId: 'your-project-id'       # Vercel project ID
  teamId: 'your-team-id'             # Vercel team ID
  
netlify:
  siteId: 'your-site-id'             # Netlify site ID
  buildCommand: 'ao-forge build'     # Build command
  publishDirectory: './dist'         # Publish directory

Configuration Options

Project Options

OptionTypeDefaultDescription
namestring-Project name
versionstring'1.0.0'Project version
descriptionstring-Project description
frameworkstring-Framework ('nextjs' or 'nuxtjs')
packageManagerstring'pnpm'Package manager

AO Process Options

OptionTypeDefaultDescription
luaFilesarrayList of Lua files
autoStartbooleanfalseAuto-start processes
processNamestring-Default process name
processesarrayProcess configurations

Development Options

OptionTypeDefaultDescription
ports.devnumber3000Development server port
ports.aonumber8080AO process port
ports.monitoringnumber9090Monitoring port
debugbooleanfalseDebug mode
hotReloadbooleantrueHot reloading

Build Options

OptionTypeDefaultDescription
build.outputstring'./dist'Output directory
build.optimizebooleantrueEnable optimization
build.sourceMapsbooleanfalseGenerate source maps
build.minifybooleantrueMinify assets

Deployment Options

OptionTypeDefaultDescription
deploy.platformstring-Deployment platform
deploy.environmentstring'production'Environment
deploy.domainstring-Deployment domain

Environment-Specific Configuration

Development Environment

# config/development.yml
ports:
  dev: 3000
debug: true
hotReload: true
sourceMaps: true

Staging Environment

# config/staging.yml
ports:
  dev: 3001
debug: false
hotReload: false
build:
  optimize: true
  sourceMaps: true

Production Environment

# config/production.yml
ports:
  dev: 3000
debug: false
hotReload: false
build:
  optimize: true
  sourceMaps: false
  minify: true

Configuration Validation

Validation Rules

# Validation configuration
validation:
  required:
    - framework
    - packageManager
    - luaFiles
  optional:
    - ports
    - build
    - deploy
  types:
    framework: ['nextjs', 'nuxtjs']
    packageManager: ['npm', 'pnpm', 'yarn']

Validation Commands

# Validate configuration
ao-forge config validate

# Check for errors
ao-forge config validate --strict

# Fix configuration issues
ao-forge config fix

Configuration Management

Using CLI Commands

# Get configuration value
ao-forge config get framework

# Set configuration value
ao-forge config set framework nextjs

# List all configuration
ao-forge config list

# Reset to defaults
ao-forge config reset

Environment Variables

# Override configuration with environment variables
export AO_FRAMEWORK=nextjs
export AO_PACKAGE_MANAGER=pnpm
export AO_PORT=3000

Best Practices

Configuration Management

  1. Use version control for configuration files
  2. Document configuration options
  3. Validate configuration before deployment
  4. Use environment-specific configurations
  5. Keep secrets in environment variables

Security

  1. Never commit sensitive information
  2. Use environment variables for secrets
  3. Validate inputs in configuration
  4. Use secure defaults for production
  5. Regularly review configuration security

Examples

Basic Configuration

name: 'my-ao-app'
framework: 'nextjs'
packageManager: 'pnpm'
luaFiles: ['counter.lua']
autoStart: false
ports:
  dev: 3000

Advanced Configuration

name: 'my-ao-app'
version: '1.0.0'
description: 'My AO-powered application'
framework: 'nextjs'
packageManager: 'pnpm'

# AO processes
luaFiles: ['counter.lua', 'token.lua']
autoStart: false
processName: 'my-process'

# Development
ports:
  dev: 3000
  ao: 8080
  monitoring: 9090

# Build
build:
  output: './dist'
  optimize: true
  sourceMaps: false

# Deployment
deploy:
  platform: 'vercel'
  environment: 'production'
  domain: 'my-app.vercel.app'

Troubleshooting

Common Issues

  1. Configuration not found
    Error: Configuration file not found
Solution: Run 'ao-forge config init' to create default configuration
  2. Invalid configuration
    Error: Invalid configuration value
Solution: Use 'ao-forge config validate' to check for errors
  3. Configuration not applied
    Error: Configuration not applied
Solution: Restart development server or reload configuration
Table of Contents