> ## 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.

# Templates

> Choose the right template for your Mizu project

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:

```bash theme={null}
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.

```bash theme={null}
mizu new learn-mizu --template minimal
```

### Are you building a REST API?

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

```bash theme={null}
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.

```bash theme={null}
mizu new my-service --template contract
```

### Are you building a website with HTML pages?

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

```bash theme={null}
mizu new my-website --template web
```

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

**Use `live`** - Includes WebSocket support and live view rendering.

```bash theme={null}
mizu new my-app --template live
```

### Do you need offline support with data sync?

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

```bash theme={null}
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`:

```bash theme={null}
# 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:

```go theme={null}
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

```bash theme={null}
mizu new myapp --template api
cd myapp
go mod tidy
mizu dev
```

### With Custom Module Path

```bash theme={null}
mizu new myapp --template api --module github.com/myname/myapp
```

### Preview Before Creating

```bash theme={null}
mizu new myapp --template api --dry-run
```

## Explore Each Template

<CardGroup cols={2}>
  <Card title="Minimal Template" icon="feather" href="/cli/minimal/overview">
    Single-file starting point for learning
  </Card>

  <Card title="API Template" icon="server" href="/cli/api/overview">
    JSON API with feature-based structure
  </Card>

  <Card title="Contract Template" icon="file-contract" href="/cli/contract-template/overview">
    Multi-protocol service with OpenAPI
  </Card>

  <Card title="Web Template" icon="browser" href="/cli/web/overview">
    Full-stack web app with views
  </Card>

  <Card title="Live Template" icon="bolt" href="/cli/live/overview">
    Real-time app with WebSockets
  </Card>

  <Card title="Sync Template" icon="rotate" href="/cli/sync/overview">
    Offline-first app with data sync
  </Card>
</CardGroup>

## 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