Quick Start

This guide gets you from zero to running app as fast as possible. You’ll create a simple JSON API with one route.

Prerequisites

Go 1.22 or later installed (download)
A terminal and text editor

Verify Go is installed:

go version
# go version go1.22.0 darwin/arm64

Step 1: Create a project

mkdir myapp && cd myapp
go mod init myapp

Step 2: Install Mizu

go get github.com/go-mizu/mizu

Step 3: Create main.go

Create a file named main.go:

package main

import "github.com/go-mizu/mizu"

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

    app.Get("/", func(c *mizu.Ctx) error {
        return c.JSON(200, map[string]string{
            "message": "Hello, Mizu!",
        })
    })

    app.Listen(":3000")
}

Step 4: Run it

go run main.go

You’ll see:

INFO server starting addr=:3000

Step 5: Test it

Open a new terminal and run:

curl http://localhost:3000

You’ll get:

{"message":"Hello, Mizu!"}

Press Ctrl+C in the first terminal to stop the server.

What just happened?

mizu.New() created an app with a router and default middleware
app.Get("/", ...) registered a handler for GET requests to ”/”
c.JSON(200, ...) sent a JSON response with status 200
app.Listen(":3000") started the HTTP server

Add more routes

Expand your main.go:

package main

import "github.com/go-mizu/mizu"

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

    // Homepage
    app.Get("/", func(c *mizu.Ctx) error {
        return c.JSON(200, map[string]string{
            "message": "Hello, Mizu!",
        })
    })

    // Get user by ID
    app.Get("/users/{id}", func(c *mizu.Ctx) error {
        id := c.Param("id")
        return c.JSON(200, map[string]string{
            "id":   id,
            "name": "User " + id,
        })
    })

    // Create a user
    app.Post("/users", func(c *mizu.Ctx) error {
        var input struct {
            Name string `json:"name"`
        }
        if err := c.BindJSON(&input, 1<<20); err != nil {
            return c.JSON(400, map[string]string{"error": err.Error()})
        }
        return c.JSON(201, map[string]string{
            "id":   "123",
            "name": input.Name,
        })
    })

    app.Listen(":3000")
}

Test the new routes:

# Get a user
curl http://localhost:3000/users/42

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Project structure

For larger apps, organize code into packages:

myapp/
├── main.go           # Entry point
├── go.mod
├── go.sum
├── handlers/         # HTTP handlers
│   └── users.go
├── services/         # Business logic
│   └── user.go
└── models/           # Data types
    └── user.go

What’s next?

Core Concepts

Learn how Mizu components work together.

Build an API

Create a complete REST API tutorial.

Project Structure

Best practices for organizing your code.

Deployment

Deploy your app to production.

Overview

Getting Started

Core Concepts

Building Your App

Deployment

Learn More

Prerequisites

Step 1: Create a project

Step 2: Install Mizu

Step 3: Create main.go

Step 4: Run it

Step 5: Test it

What just happened?

Add more routes

Project structure

What’s next?

Core Concepts

Build an API

Project Structure

Deployment

​Prerequisites

​Step 1: Create a project

​Step 2: Install Mizu

​Step 3: Create main.go

​Step 4: Run it

​Step 5: Test it

​What just happened?

​Add more routes

​Project structure

​What’s next?

Core Concepts

Build an API

Project Structure

Deployment

Prerequisites

Step 1: Create a project

Step 2: Install Mizu

Step 3: Create main.go

Step 4: Run it

Step 5: Test it

What just happened?

Add more routes

Project structure

What’s next?