Development Workflow

Learn how to use ao-forge dev effectively with AOS CLI integration for a smooth development experience.

Overview

The development workflow in ao-forge combines frontend development with AO process management, providing a seamless experience for building AO-powered applications.

Basic Development Commands

# Start development server only
ao-forge dev

# Start both development server and AO processes
ao-forge dev:ao

# Start with monitoring
ao-forge dev:ao -m

# Start with process evaluation
ao-forge dev:ao -e "your-eval-input"

Development Server

Frontend Development

# Start Next.js development server
ao-forge dev --framework nextjs

# Start Nuxt.js development server
ao-forge dev --framework nuxtjs

# Custom port
ao-forge dev --port 3001

# Open browser automatically
ao-forge dev --open

Hot Reloading

The development server includes:

  • Hot module replacement for frontend changes
  • Live reloading for configuration changes
  • Error overlay for debugging
  • TypeScript support with type checking

AO Process Management

Starting AO Processes

# Start with default configuration
ao-forge dev:ao

# Start with custom process name
ao-forge dev:ao --process my-process

# Start with specific wallet
ao-forge dev:ao --wallet ./wallet.json

# Start with monitoring
ao-forge dev:ao --monitor

Process Configuration

# ao.config.yml
luaFiles: ['counter.lua', 'token.lua']
packageManager: 'pnpm'
framework: 'nextjs'
autoStart: true
ports:
  dev: 3000
processName: 'my-process'
monitoring: true

AOS CLI Integration

Using AOS CLI Directly

# Install AOS CLI
npm i -g https://get_ao.g8way.io

# Start a process
aos my-process

# Load a contract
aos my-process --load ./ao/contract.lua

# Send a message
aos my-process --eval "Send({Target = 'process-id', Action = 'increment'})"

Integrated Workflow

# ao-forge handles AOS CLI integration
ao-forge dev:ao

# This automatically:
# 1. Starts the frontend development server
# 2. Initializes AO processes
# 3. Loads Lua contracts
# 4. Sets up monitoring
# 5. Provides process endpoints

Development Features

Process Monitoring

# Monitor process activity
ao-forge dev:ao --monitor

# Watch specific process
ao-forge dev:ao --watch my-process

# View process logs
ao-forge dev:ao --logs

Debugging

# Enable debug mode
ao-forge dev:ao --debug

# Verbose logging
ao-forge dev:ao --verbose

# Step-by-step execution
ao-forge dev:ao --step

Environment Configuration

Development Environment

# Set environment
export NODE_ENV=development

# Set AO environment
export AO_ENV=testnet

# Set custom configuration
export AO_CONFIG=./config/dev.yml

Environment Variables

# Frontend environment
NEXT_PUBLIC_AO_PROCESS_ID=your-process-id
NEXT_PUBLIC_AO_GATEWAY=https://arweave.net

# AO environment
AO_WALLET_PATH=./wallet.json
AO_GATEWAY=https://arweave.net
AO_MODULE=your-module-id

Workflow Best Practices

1. Start with Development Server

# Always start with the development server
ao-forge dev

2. Add AO Processes Gradually

# Start with one process
ao-forge dev:ao --process counter

# Add more processes as needed
ao-forge dev:ao --process token
ao-forge dev:ao --process dao

3. Use Monitoring

# Always use monitoring in development
ao-forge dev:ao --monitor

4. Test Frequently

# Test your processes regularly
ao-forge test

# Run specific tests
ao-forge test --process counter

Common Workflows

New Feature Development

  1. Start development server: ao-forge dev
  2. Create new process: ao-forge ai generate process feature
  3. Test process: ao-forge test --process feature
  4. Integrate with frontend
  5. Deploy: ao-forge build

Bug Fixing

  1. Enable debug mode: ao-forge dev:ao --debug
  2. Monitor process activity: ao-forge dev:ao --monitor
  3. Check logs: ao-forge dev:ao --logs
  4. Fix issues and test
  5. Deploy fix: ao-forge build

Performance Optimization

  1. Profile processes: ao-forge profile
  2. Monitor resource usage: ao-forge dev:ao --monitor
  3. Optimize code
  4. Test performance: ao-forge test --performance
  5. Deploy optimized version: ao-forge build

Troubleshooting

Common Issues

  1. Port already in use
    # Kill process using port
lsof -i :3000
kill -9 <PID>
  2. AO process not starting
    # Check AOS CLI installation
aos --version

# Check wallet
aos --wallet ./wallet.json
  3. Frontend not connecting to AO
    # Check process ID
ao-forge process list

# Verify configuration
ao-forge config validate

Getting Help

# Get help with dev commands
ao-forge dev --help

# Check status
ao-forge status

# View logs
ao-forge logs
Table of Contents