Templates - 💧 Mizu

When you create a new project with mizu new, you choose a template. Templates are starter projects that give you a solid foundation with all the boilerplate already set up. Each template is designed for a specific use case, from simple learning projects to complex real-time applications.

Available Templates

The Mizu CLI includes 6 built-in templates:

Template	Description	Best For
minimal	Smallest runnable project	Learning, quick experiments
api	JSON API service	REST APIs, backend services
contract	Multi-protocol service	APIs with REST + JSON-RPC
web	Full-stack web app	Server-rendered websites
live	Real-time app	Chat, dashboards, live updates
sync	Offline-first app	Collaborative apps, offline support

List Templates

See all available templates:

mizu new --list

Output:

Template    Purpose
api         JSON API service with a recommended layout
contract    Transport-neutral service contract with REST, JSON-RPC, and OpenAPI
live        Real-time interactive app with live views and instant updates
minimal     Smallest runnable Mizu project
sync        Offline-first app with sync, live updates, and reactive state
web         Full-stack web app with views, components, and static assets

Which Template Should I Use?

Use this decision guide to pick the right template:

Are you learning Mizu?

Use minimal - It has the least amount of code, making it easy to understand how Mizu works.

mizu new learn-mizu --template minimal

Are you building a REST API?

Use api - It includes a recommended project structure with feature-based organization.

mizu new my-api --template api

Do you need multiple protocols (REST + JSON-RPC)?

Use contract - Define your API once, expose it via multiple transports.

mizu new my-service --template contract

Are you building a website with HTML pages?

Use web - Includes view templates, layouts, and static asset handling.

mizu new my-website --template web

Do you need real-time updates (like chat)?

Use live - Includes WebSocket support and live view rendering.

mizu new my-app --template live

Do you need offline support with data sync?

Use sync - The most advanced template with offline-first architecture.

mizu new my-app --template sync

Template Comparison

Complexity Level

minimal ─────────────────────────────────────► sync
  |           |           |           |          |
simple      api        web/live    contract   advanced

Features Included

Feature	minimal	api	contract	web	live	sync
Single file	Yes	-	-	-	-	-
Feature-based structure	-	Yes	Yes	Yes	Yes	Yes
JSON responses	Yes	Yes	Yes	Yes	Yes	Yes
HTML templates	-	-	-	Yes	Yes	Yes
Static assets	-	-	-	Yes	Yes	Yes
JSON-RPC	-	-	Yes	-	-	-
OpenAPI generation	-	-	Yes	-	-	-
WebSocket	-	-	-	-	Yes	Yes
Live updates	-	-	-	-	Yes	Yes
Offline support	-	-	-	-	-	Yes
Data sync	-	-	-	-	-	Yes

Common Patterns

Starting Simple, Then Growing

Start with minimal to learn, then create a new project with api:

# Day 1: Learn Mizu
mizu new learn --template minimal
cd learn
go mod tidy
mizu dev

# Day 2: Build a real project
cd ..
mizu new my-api --template api
cd my-api
go mod tidy
mizu dev

Prototyping to Production

Start with minimal for a quick prototype, then migrate to api for production:

Build your prototype with minimal
Validate your idea works
Create a new api project
Copy your business logic over
Enjoy the better structure

Frontend + Backend

For apps with both a frontend and backend:

API only (frontend in React/Vue): Use api
Server-rendered HTML: Use web
Real-time features: Use live or sync

Template Architecture

All templates share these principles:

Embedded in CLI

Templates are built into the CLI binary. This means:

No network required to create projects
Templates always match CLI version
Works offline

Go Module Ready

Every template creates a valid go.mod file:

module {{.Module}}

go 1.22

require github.com/go-mizu/mizu v0.x.x

Common Files

All templates include:

File	Purpose
`go.mod`	Go module definition
`.gitignore`	Git ignore rules
`README.md`	Project documentation

Creating Projects

Basic Creation

mizu new myapp --template api
cd myapp
go mod tidy
mizu dev

With Custom Module Path

mizu new myapp --template api --module github.com/myname/myapp

Preview Before Creating

mizu new myapp --template api --dry-run

Explore Each Template

Minimal Template

Single-file starting point for learning

API Template

JSON API with feature-based structure

Contract Template

Multi-protocol service with OpenAPI

Web Template

Full-stack web app with views

Live Template

Real-time app with WebSockets

Sync Template

Offline-first app with data sync

Next Steps

Pick a template and explore its detailed documentation
Run mizu new --template <name> --dry-run to preview any template
Check out the tutorials for hands-on guides

​Available Templates

​List Templates

​Which Template Should I Use?

​Are you learning Mizu?

​Are you building a REST API?

​Do you need multiple protocols (REST + JSON-RPC)?

​Are you building a website with HTML pages?

​Do you need real-time updates (like chat)?

​Do you need offline support with data sync?

​Template Comparison

​Complexity Level

​Features Included

​Common Patterns

​Starting Simple, Then Growing

​Prototyping to Production

​Frontend + Backend

​Template Architecture

​Embedded in CLI

​Go Module Ready

​Common Files

​Creating Projects

​Basic Creation

​With Custom Module Path

​Preview Before Creating

​Explore Each Template