Development Commands

The forge dev command provides development tools and server management for local development. It supports hot reload, app discovery, and interactive development workflows.

Main Command

`forge dev`

Start development server and tools.

forge dev                    # Interactive app selection
forge dev -a api-gateway     # Run specific app
forge dev -a api -p 8080     # Run on specific port
forge dev --watch            # With hot reload (default)

Flags:

-a, --app - App to run
-w, --watch - Watch for changes (default: true)
-p, --port - Port number

Behavior:

If no app is specified, shows an interactive app selector
Automatically discovers apps in your project
Supports both single-module and multi-module layouts
Sets PORT environment variable if specified

Subcommands

`forge dev list` (aliases: `ls`)

List all available apps in your project.

forge dev list
forge dev ls

Output: Shows a table with app information:

Name: App name
Type: App type (usually "app")
Location: Path to app directory
Status: Ready status

Example Output:

┌─────────────┬──────┬─────────────────┬────────┐
│ Name        │ Type │ Location        │ Status │
├─────────────┼──────┼─────────────────┼────────┤
│ api-gateway │ app  │ cmd/api-gateway │ ✓ Ready│
│ auth-service│ app  │ cmd/auth-service│ ✓ Ready│
└─────────────┴──────┴─────────────────┴────────┘

`forge dev build`

Build app for development.

forge dev build -a api-gateway
forge dev build --app auth-service

Flags:

-a, --app - App to build (required)

Behavior:

Builds the specified app using go build
Outputs to bin/<app-name> directory
Shows build progress with spinner
Displays success/failure status

App Discovery

Forge automatically discovers apps in your project based on the layout:

Single-Module Layout

For single-module projects, Forge scans the cmd/ directory:

my-project/
├── cmd/
│   ├── api-gateway/
│   │   └── main.go
│   ├── auth-service/
│   │   └── main.go
│   └── worker/
│       └── main.go
└── .forge.yaml

Multi-Module Layout

For multi-module projects, Forge scans the apps/ directory:

my-project/
├── apps/
│   ├── api-gateway/
│   │   └── cmd/
│   │       └── server/
│   │           └── main.go
│   ├── auth-service/
│   │   └── cmd/
│   │       └── server/
│   │           └── main.go
│   └── worker/
│       └── cmd/
│           └── server/
│               └── main.go
└── .forge.yaml

Development Features

Hot Reload

Hot reload automatically restarts your application when files change:

forge dev --watch

Note: Hot reload is currently in development. The command will show a warning and run in normal mode.

Port Configuration

Set a custom port for your application:

forge dev -p 3000
forge dev --port 8080

This sets the PORT environment variable that your application can read.

Interactive App Selection

When no app is specified, Forge shows an interactive selector:

forge dev

Output:

? Select app to run: 
  ▸ api-gateway
    auth-service
    worker

Project Requirements

Forge Project

The forge dev command requires a Forge project with a .forge.yaml file:

# If not in a Forge project
forge dev
# Error: no .forge.yaml found in current directory or any parent
# This doesn't appear to be a Forge project.
# To initialize a new project, run:
#   forge init

App Structure

Each app must have a main.go file with a main() function:

package main

import (
    "log"
    "github.com/xraph/forge"
)

func main() {
    app := forge.NewApp(forge.AppConfig{
        Name:    "my-app",
        Version: "0.1.0",
    })

    // Register routes
    app.Router().GET("/", func(c forge.Context) error {
        return c.JSON(200, forge.Map{
            "message": "Hello from my-app!",
        })
    })

    // Start server
    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

Configuration

Development Configuration

Configure development settings in .forge.yaml:

dev:
  port: 8080
  hot_reload: true
  debug: true
  extensions:
    - auth
    - database

Environment Variables

Set environment variables for development:

export PORT=3000
export DEBUG=true
export LOG_LEVEL=debug

forge dev

Troubleshooting

No Apps Found

If no apps are found:

forge dev
# Warning: No apps found. Create one with: forge generate app

Solution:

forge generate app --name=my-app

App Not Found

If the specified app doesn't exist:

forge dev -a nonexistent-app
# Error: app not found: nonexistent-app

Solution:

# List available apps
forge dev list

# Or create the app
forge generate app --name=nonexistent-app

Build Failures

If app build fails:

forge dev build -a my-app
# ✗ Build failed

Common causes:

Missing dependencies
Syntax errors in code
Missing main.go file

Solution:

# Check for syntax errors
go build ./cmd/my-app

# Install dependencies
go mod tidy

# Verify main.go exists
ls cmd/my-app/main.go

Best Practices

Use Interactive Mode: Let Forge discover and select apps automatically
Set Custom Ports: Use -p flag for port conflicts
Enable Hot Reload: Use --watch for faster development
Check App Status: Use forge dev list to verify apps
Build Before Dev: Use forge dev build to catch build errors early

For more information about code generation, see the Code Generation Commands documentation.

Development Commands

On this page