Getting Started

Set up your first Gastro project in under a minute. You'll need Go 1.26+ installed.

Install the CLI

Build the gastro CLI from source. If you use mise, it will manage your Go toolchain automatically.

# Build the gastro CLI from source
go build -o gastro ./cmd/gastro/

# Or with mise (managed tooling)
mise install

Project Structure

A Gastro project has a simple, opinionated layout:

myapp/
  pages/
    index.gastro
  static/
    styles.css
  main.go
  go.mod

pages/ — .gastro files that become HTTP routes
components/ — reusable .gastro components
static/ — CSS, images, and other static files served at /static/
main.go — your application entry point

Your First Page

Create pages/index.gastro. The code between --- delimiters is Go frontmatter that runs on the server. The HTML below is rendered with Go's html/template.

---
import "time"

Title := "Hello, Gastro"
Year := time.Now().Year()
---
<!DOCTYPE html>
<html>
<head><title>{{ .Title }}</title></head>
<body>
    <h1>{{ .Title }}</h1>
    <p>Copyright {{ .Year }}</p>
</body>
</html>

Uppercase variables like Title and Year are automatically exported to the template as {{ .Title }} and {{ .Year }}. Lowercase variables stay private.

Entry Point

Create main.go that imports the generated code and starts the server:

package main

import (
    "fmt"
    "net/http"
    "os"

    gastro "myapp/.gastro"
)

func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "4242"
    }
    fmt.Printf("Listening on http://localhost:%s\n", port)
    http.ListenAndServe(":"+port, gastro.Routes())
}

The .gastro/ directory contains generated Go code. Import it as a package with any alias you like.

Build & Run

# Generate Go code from .gastro files
gastro generate

# Build the binary
go build -o myapp .

# Run
./myapp

Open http://localhost:4242 to see your page.

Development Mode

For development, use the gastro dev command. It watches for file changes, regenerates code, and restarts the server automatically. Template changes are hot-reloaded without a restart.

# Watches for changes, rebuilds, restarts server
gastro dev

Pages & Routing