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
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 | Code | What it does |
|---|
| 1 | package main | Marks this as an executable program |
| 4 | "log" | Import Go’s logging package |
| 5 | "github.com/go-mizu/mizu" | Import the Mizu framework |
| 8 | func main() | Entry point - runs when you start the app |
| 9 | app := mizu.New() | Create a new Mizu application |
| 11 | app.Get("/", ...) | Register a handler for GET / |
| 12 | func(c *mizu.Ctx) error | Handler function signature |
| 13 | return c.Text(200, ...) | Send HTTP 200 with text |
| 16 | log.Println(...) | Log that we’re starting |
| 17 | app.Listen(":8080") | Start server on port 8080 |
| 18 | log.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
| Line | Meaning |
|---|
module example.com/myapp | Your project’s import path |
go 1.22 | Minimum Go version required |
require github.com/go-mizu/mizu | Dependency 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
README.md
Basic project documentation:
# myapp
A Mizu application.
## Getting Started
```bash
go mod tidy
mizu dev
## Understanding the Code
### The Handler
```go
app.Get("/", func(c *mizu.Ctx) error {
return c.Text(200, "Hello from myapp\n")
})
app.Get - Registers this handler for GET requests"/" - The URL path to matchfunc(c *mizu.Ctx) error - The handler functionc - The context, contains request info and response methodsc.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:
- main.go is over 100 lines - Time to split into multiple files
- You have related routes - Group them into packages
- You need configuration - Add a config file/struct
- Multiple developers - Need clearer organization
At this point, consider using the api template or building your own structure.
Next Steps