> ## 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. # New > Create a new Mizu project from a template The `mizu new` command creates a new Mizu project by generating files from a template. Think of templates as starter kits - each one sets up a complete project structure so you can start coding right away instead of creating files manually. ## Basic Usage ```bash theme={null} mizu new [path] --template ``` **Arguments:** * `[path]` - Where to create the project (optional, defaults to current directory) * `--template` - Which template to use (required) ## Quick Examples ```bash theme={null} # Create a minimal project in current directory mizu new . --template minimal # Create an API project in a new folder mizu new myapi --template api # Create a web app with a custom module name mizu new webapp --template web --module github.com/myname/webapp # Preview what will be created (without creating anything) mizu new myapp --template api --dry-run ``` ## Understanding the Command When you run `mizu new myapp --template api`, here's what happens: 1. **Creates the directory** - A new folder called `myapp` is created 2. **Generates files** - Template files are copied with your project name filled in 3. **Sets up Go module** - The `go.mod` file is created with the correct module path 4. **Reports success** - Shows you what was created Example output: ``` Created myapp from template api 5 directories, 12 files Next steps: cd myapp go mod tidy mizu dev ``` ## Available Templates To 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 ``` ## Flags Reference ### Required Flags | Flag | Short | Description | | ------------------- | ----- | ------------------- | | `--template ` | `-t` | The template to use | ### Optional Flags | Flag | Description | Default | | ------------------- | ---------------------------------------------------- | -------------------- | | `--list` | List available templates | - | | `--dry-run` | Show what would be created without creating anything | - | | `--force` | Overwrite existing files | - | | `--name ` | Project name | Derived from path | | `--module ` | Go module path | `example.com/` | | `--license ` | License identifier | `MIT` | | `--var key=value` | Custom template variable (repeatable) | - | ## Detailed Flag Explanations ### --template, -t (Required) Specifies which template to use. This is the only required flag. ```bash theme={null} # Using long form mizu new myapp --template api # Using short form mizu new myapp -t api ``` If you forget to specify a template: ``` error: template is required Run 'mizu new --list' to see available templates. ``` ### --list Lists all available templates without creating a project. ```bash theme={null} mizu new --list ``` This is helpful when you forget the template names. ### --dry-run Shows exactly what files would be created without actually creating them. This is useful for: * Previewing the project structure * Checking for conflicts before overwriting * Understanding what a template includes ```bash theme={null} mizu new myapp --template api --dry-run ``` Output: ``` Plan for template: api Target: /Users/you/projects/myapp Operations: mkdir cmd mkdir cmd/api mkdir app mkdir app/api mkdir feature mkdir feature/hello write go.mod write main.go write cmd/api/main.go write app/api/app.go write app/api/config.go write app/api/routes.go write feature/hello/http.go ... ``` ### --force Overwrites existing files without asking. Use this carefully! ```bash theme={null} # This will overwrite any existing files mizu new myapp --template api --force ``` Without `--force`, if files already exist: ``` error: files already exist: go.mod main.go Use --force to overwrite. ``` ### --name Sets the project name explicitly. By default, the name is derived from the path. ```bash theme={null} # Name will be "myapp" mizu new myapp --template api # Override the name mizu new myapp --template api --name my-cool-app ``` The name is used in: * Package names * Log messages * Config files ### --module Sets the Go module path. This is important for imports within your project. ```bash theme={null} # Default: example.com/myapp mizu new myapp --template api # Custom module path mizu new myapp --template api --module github.com/myname/myapp ``` **What is a module path?** A Go module path is a unique identifier for your project. It's used when: * Other packages import your code * You run `go get` to download your project * Go resolves dependencies Common patterns: * `github.com/username/project` - For GitHub projects * `example.com/project` - For local development * `company.com/team/project` - For internal projects ### --license Sets the license identifier. Default is `MIT`. ```bash theme={null} mizu new myapp --template api --license Apache-2.0 ``` This affects the LICENSE file content in templates that include one. ### --var (Custom Variables) Pass custom variables to templates. This flag can be used multiple times. ```bash theme={null} mizu new myapp --template api --var port=3000 --var db=postgres ``` Custom variables are available in templates as `.Vars.key`. Template authors can document which variables their templates support. ## Working with Paths ### Current Directory Create files in the current directory: ```bash theme={null} # Using "." mizu new . --template minimal # Or omit the path entirely (same effect) cd myproject mizu new --template minimal ``` ### New Directory Create a new directory for the project: ```bash theme={null} mizu new myapp --template api ``` ### Nested Path Create a project in a nested path: ```bash theme={null} mizu new projects/backend/api --template api ``` All necessary parent directories are created automatically. ### Absolute Path You can also use absolute paths: ```bash theme={null} mizu new /Users/me/projects/myapp --template api ``` ## JSON Output For scripting and automation, use `--json`: ```bash theme={null} mizu new myapp --template api --json ``` Output: ```json theme={null} { "template": "api", "path": "/Users/you/projects/myapp", "operations": [ {"type": "mkdir", "path": "cmd"}, {"type": "mkdir", "path": "cmd/api"}, {"type": "write", "path": "go.mod", "size": 156}, {"type": "write", "path": "cmd/api/main.go", "size": 423} ], "summary": { "directories": 5, "files": 12 } } ``` ### JSON with Dry Run Combine `--json` with `--dry-run` to get a machine-readable plan: ```bash theme={null} mizu new myapp --template api --dry-run --json ``` ### JSON Error Output Errors are also returned as JSON: ```json theme={null} { "error": "unknown_template", "message": "unknown template: badname" } ``` ## Common Workflows ### Start a New Project The most common workflow: ```bash theme={null} # 1. Create the project mizu new myapp --template api # 2. Enter the project directory cd myapp # 3. Download dependencies go mod tidy # 4. Start development mizu dev ``` ### Preview Before Creating If you're unsure what a template contains: ```bash theme={null} # See what will be created mizu new myapp --template api --dry-run # If it looks good, create it mizu new myapp --template api ``` ### Start Fresh If you want to reset a project to the template defaults: ```bash theme={null} # This overwrites all files mizu new . --template api --force ``` Using `--force` will overwrite your existing code! Make sure you have a backup or have committed your changes to git first. ### Scripted Project Creation For automation (CI/CD, scripts): ```bash theme={null} #!/bin/bash mizu new myapp --template api --module "github.com/company/myapp" --json > result.json if [ $? -eq 0 ]; then echo "Project created successfully" cd myapp && go mod tidy else echo "Failed to create project" cat result.json exit 1 fi ``` ## Template Variables Templates have access to these built-in variables: | Variable | Description | Example | | --------- | ------------------ | --------------------- | | `Name` | Project name | `myapp` | | `Module` | Go module path | `github.com/me/myapp` | | `License` | License identifier | `MIT` | | `Year` | Current year | `2024` | Plus any custom variables you pass with `--var`. ## Error Messages ### Unknown Template ``` error: unknown template "badname" Run 'mizu new --list' to see available templates. ``` **Fix:** Use `mizu new --list` to see valid template names. ### Files Already Exist ``` error: files already exist: go.mod main.go Use --force to overwrite. ``` **Fix:** Either use `--force` to overwrite, or choose a different path. ### Invalid Path ``` error: path "/root/project" is not writable ``` **Fix:** Choose a path where you have write permissions. ## Exit Codes | Code | Meaning | | ---- | ---------------------------------------------- | | 0 | Success | | 1 | Error (template error, file system error) | | 2 | Usage error (missing flags, invalid arguments) | ## Next Steps After creating a project: Start the development server Learn what each template includes