Getting Started

This guide will walk you through creating your first irgo application, running it in development mode, and building it for different platforms.

Install the CLI

Install the irgo CLI using Go:

go install github.com/stukennedy/irgo/cmd/irgo@latest

Or build from source:

git clone https://github.com/stukennedy/irgo.gitcd irgo/cmd/irgogo install .

Verify the installation:

irgo version

Create a New Project

irgo new myappcd myappgo mod tidybun install  # or: npm install

This creates a new project with the following structure:

myapp/├── main.go              # Mobile/web entry point├── main_desktop.go      # Desktop entry point├── go.mod               # Go module definition├── .air.toml            # Hot reload configuration├── package.json         # Node dependencies (Tailwind 4)├── app/│   └── app.go           # Router setup├── handlers/│   └── handlers.go      # HTTP handlers├── templates/│   ├── layout.templ     # Base HTML layout│   ├── home.templ       # Home page template│   └── components.templ # Reusable components└── static/    ├── css/    │   ├── input.css    # Tailwind source    │   └── output.css   # Generated CSS    └── js/        ├── htmx.min.js  # HTMX library (downloaded automatically)        └── hx-ws.js     # HTMX WebSocket extension

Development Mode

Web Development (Hot Reload)

irgo dev

This starts a development server at http://localhost:8080 with hot reload. Edit your Go or templ files and see changes instantly.

Desktop Development

irgo run desktop         # Run as desktop appirgo run desktop --dev   # With browser devtools enabled

iOS Development

irgo run ios --dev       # Hot reload with iOS Simulatorirgo run ios             # Production build

Android Development

irgo run android --dev   # Hot reload with Android Emulatorirgo run android         # Production build

Building for Production

Desktop

irgo build desktop           # Build for current platformirgo build desktop macos     # Build macOS .app bundleirgo build desktop windows   # Build Windows .exeirgo build desktop linux     # Build Linux binary

Mobile

irgo build ios               # Build iOS frameworkirgo build android           # Build Android AARirgo build all               # Build for all mobile platforms

Your First Handler

Let's create a simple counter to understand the irgo pattern.

1. Create the Handler

handlers/counter.go
package handlersimport (    "strconv"    "myapp/templates"    "github.com/stukennedy/irgo/pkg/render"    "github.com/stukennedy/irgo/pkg/router")var count = 0func GetCounter(ctx *router.Context) (string, error) {    return renderer.Render(templates.Counter(count))}func IncrementCounter(ctx *router.Context) (string, error) {    count++    return renderer.Render(templates.Counter(count))}func DecrementCounter(ctx *router.Context) (string, error) {    count--    return renderer.Render(templates.Counter(count))}

2. Create the Template

templates/counter.templ
package templatesimport "fmt"templ Counter(count int) {    <div id="counter" class="counter">        <h2>Count: { fmt.Sprintf("%d", count) }</h2>        <div class="buttons">            <button                hx-post="/counter/decrement"                hx-target="#counter"                hx-swap="outerHTML"            >-</button>            <button                hx-post="/counter/increment"                hx-target="#counter"                hx-swap="outerHTML"            >+</button>        </div>    </div>}

3. Register the Routes

app/app.go
package appimport (    "myapp/handlers"    "github.com/stukennedy/irgo/pkg/router")func NewRouter() *router.Router {    r := router.New()    // Counter routes    r.GET("/counter", handlers.GetCounter)    r.POST("/counter/increment", handlers.IncrementCounter)    r.POST("/counter/decrement", handlers.DecrementCounter)    return r}

4. Generate Templates and Run

irgo templ      # Generate _templ.go filesirgo dev        # Start development server

Visit http://localhost:8080/counter - you now have a working counter with HTMX-powered interactions!

Tip

Notice how the handler returns HTML fragments, not JSON. HTMX swaps the #counterelement with the new HTML. This is the hypermedia pattern at work.

Next Steps