Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

The minimal template creates the simplest possible project structure. This page explains every file so you understand exactly what you’re working with. Don’t worry if some concepts are new - we’ll explain everything.

​
Directory Layout

myapp/
├── go.mod       # Go module definition
├── main.go      # Your application code
├── .gitignore   # Git ignore rules
└── README.md    # Project documentation
That’s only 4 files!

​
File Details

​
main.go

This is your entire application: 
package main

import (
    "log"
    "github.com/go-mizu/mizu"
)

func main() {
    app := mizu.New()

    app.Get("/", func(c *mizu.Ctx) error {
        return c.Text(200, "Hello from myapp\n")
    })

    log.Println("listening on :8080")
    if err := app.Listen(":8080"); err != nil {
        log.Fatal(err)
    }
}
Line by line explanation:
LineCodeWhat it does
1package mainMarks this as an executable program
4"log"Import Go’s logging package
5"github.com/go-mizu/mizu"Import the Mizu framework
8func main()Entry point - runs when you start the app
9app := mizu.New()Create a new Mizu application
11app.Get("/", ...)Register a handler for GET /
12func(c *mizu.Ctx) errorHandler function signature
13return c.Text(200, ...)Send HTTP 200 with text
16log.Println(...)Log that we’re starting
17app.Listen(":8080")Start server on port 8080
18log.Fatal(err)Exit if server fails to start

​
go.mod

The Go module file defines your project: 
module example.com/myapp

go 1.22

require github.com/go-mizu/mizu v0.0.0
What each line means:
LineMeaning
module example.com/myappYour project’s import path
go 1.22Minimum Go version required
require github.com/go-mizu/mizuDependency on Mizu
The version v0.0.0 is a placeholder. When you run go mod tidy, it’s replaced with the actual latest version.

​
.gitignore

Tells Git which files to ignore: 
# Binaries
*.exe
*.exe~
*.dll
*.so
*.dylib

# Test binary
*.test

# Output
*.out

# Go workspace
go.work

# IDE
.idea/
.vscode/
*.swp
*.swo
This prevents compiled binaries and editor files from being committed.

​
README.md

Basic project documentation: 
# myapp

A Mizu application.

## Getting Started

```bash
go mod tidy
mizu dev
Open http://localhost:8080 

## Understanding the Code

### The Handler

```go
app.Get("/", func(c *mizu.Ctx) error {
    return c.Text(200, "Hello from myapp\n")
})
This is a handler - a function that processes HTTP requests.
  • app.Get - Registers this handler for GET requests
  • "/" - The URL path to match
  • func(c *mizu.Ctx) error - The handler function
  • c - The context, contains request info and response methods
  • c.Text(200, ...) - Send a text response with status 200

​
The Context

The *mizu.Ctx parameter gives you access to: 
// Request data
c.Param("id")       // URL parameters like /users/:id
c.Query("page")     // Query string like ?page=1
c.Body()            // Request body

// Response methods
c.Text(200, "...")  // Plain text
c.JSON(200, data)   // JSON response
c.HTML(200, "...")  // HTML response

​
Starting the Server

if err := app.Listen(":8080"); err != nil {
    log.Fatal(err)
}
  • ":8080" means “listen on port 8080 on all interfaces”
  • Listen blocks until the server is stopped
  • If it fails (port in use, etc.), we log the error and exit

​
Common Modifications

​
Change the Port

log.Println("listening on :3000")
if err := app.Listen(":3000"); err != nil {
    log.Fatal(err)
}

​
Add More Routes

app.Get("/", func(c *mizu.Ctx) error {
    return c.Text(200, "Home page")
})

app.Get("/about", func(c *mizu.Ctx) error {
    return c.Text(200, "About page")
})

app.Get("/api/users", func(c *mizu.Ctx) error {
    return c.JSON(200, []string{"Alice", "Bob"})
})

​
Add URL Parameters

app.Get("/users/:id", func(c *mizu.Ctx) error {
    id := c.Param("id")
    return c.Text(200, "User ID: "+id)
})

​
Handle POST Requests

app.Post("/users", func(c *mizu.Ctx) error {
    // Read JSON from request body
    var user struct {
        Name string `json:"name"`
    }
    if err := c.Bind(&user); err != nil {
        return err
    }
    return c.JSON(201, user)
})

​
When to Add More Structure

Signs you’ve outgrown the minimal template:
  1. main.go is over 100 lines - Time to split into multiple files
  2. You have related routes - Group them into packages
  3. You need configuration - Add a config file/struct
  4. Multiple developers - Need clearer organization
At this point, consider using the api template or building your own structure.

​
Next Steps

Tutorial

Build your first app step by step

API Template

See a more structured approach