Skip to main content
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:
TemplateDescriptionBest For
minimalSmallest runnable projectLearning, quick experiments
apiJSON API serviceREST APIs, backend services
contractMulti-protocol serviceAPIs with REST + JSON-RPC
webFull-stack web appServer-rendered websites
liveReal-time appChat, dashboards, live updates
syncOffline-first appCollaborative 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

Featureminimalapicontractweblivesync
Single fileYes-----
Feature-based structure-YesYesYesYesYes
JSON responsesYesYesYesYesYesYes
HTML templates---YesYesYes
Static assets---YesYesYes
JSON-RPC--Yes---
OpenAPI generation--Yes---
WebSocket----YesYes
Live updates----YesYes
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:
  1. Build your prototype with minimal
  2. Validate your idea works
  3. Create a new api project
  4. Copy your business logic over
  5. 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:
FilePurpose
go.modGo module definition
.gitignoreGit ignore rules
README.mdProject 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