> ## 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.
# Minimal Setup
> Manually set up frontend integration without using templates.
This guide shows you how to manually integrate a frontend framework with Mizu without using the CLI templates.
## Prerequisites
* Go 1.22+
* Node.js 18+
* Existing Mizu project or create new one
## React + Vite Setup
### 1. Create Vite Project
```bash theme={null}
npm create vite@latest frontend -- --template react-ts
cd frontend
npm install
```
### 2. Configure Vite
```ts theme={null}
// frontend/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
server: {
port: 5173,
hmr: {
clientPort: 3000, // Your Mizu server port
},
},
build: {
outDir: '../dist',
emptyOutDir: true,
},
})
```
### 3. Add Frontend Integration
```go theme={null}
// main.go or app.go
package main
import (
"embed"
"io/fs"
"github.com/go-mizu/mizu"
"github.com/go-mizu/mizu/frontend"
)
//go:embed all:dist
var distFS embed.FS
func main() {
app := mizu.New()
// API routes
app.Get("/api/hello", func(c *mizu.Ctx) error {
return c.JSON(200, map[string]string{"message": "Hello!"})
})
// Frontend middleware
dist, _ := fs.Sub(distFS, "dist")
app.Use(frontend.WithOptions(frontend.Options{
Mode: frontend.ModeAuto,
FS: dist,
Root: "./dist",
DevServer: "http://localhost:5173",
IgnorePaths: []string{"/api"},
}))
app.Listen(":3000")
}
```
### 4. Update package.json
```json theme={null}
{
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview"
}
}
```
### 5. Create Makefile (Optional)
```makefile theme={null}
.PHONY: dev build clean
dev:
@echo "Starting development servers..."
@(cd frontend && npm run dev) & \
go run main.go
build:
@echo "Building frontend..."
cd frontend && npm run build
@echo "Building backend..."
go build -o ./bin/server
clean:
rm -rf dist frontend/node_modules ./bin
```
## Vue + Vite Setup
Follow same steps as React, but:
```bash theme={null}
# Step 1: Create Vue project
npm create vite@latest frontend -- --template vue-ts
```
Same Vite config, same backend setup.
## HTMX Setup
### 1. Create Directory Structure
```bash theme={null}
mkdir -p views/{layouts,pages,partials}
mkdir -p static/{css,js}
```
### 2. Create Go Embed Files
```go theme={null}
// views/embed.go
package views
import "embed"
//go:embed layouts/* pages/* partials/*
var FS embed.FS
```
```go theme={null}
// static/embed.go
package static
import "embed"
//go:embed css/* js/*
var FS embed.FS
```
### 3. Setup App
```go theme={null}
package main
import (
"io/fs"
"github.com/go-mizu/mizu"
"github.com/go-mizu/mizu/view"
"yourmodule/static"
"yourmodule/views"
)
func main() {
app := mizu.New()
// View engine
viewsFS, _ := fs.Sub(views.FS, ".")
v := view.New(view.Config{
FS: viewsFS,
Extension: ".html",
DefaultLayout: "default",
})
app.Use(v.Middleware())
// Static files
staticFS, _ := fs.Sub(static.FS, ".")
app.Static("/static", staticFS)
// Routes
app.Get("/", func(c *mizu.Ctx) error {
return c.Render("pages/home", nil)
})
app.Listen(":3000")
}
```
### 4. Create Templates
```html theme={null}
My App
{{ embed }}
```
```html theme={null}
Welcome
Loading...
```
## Next.js Setup
### 1. Create Next.js App
```bash theme={null}
npx create-next-app@latest frontend
cd frontend
```
### 2. Configure for Static Export
```js theme={null}
// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
distDir: '../build',
images: {
unoptimized: true,
},
}
export default nextConfig
```
### 3. Backend Setup
```go theme={null}
//go:embed all:build
var buildFS embed.FS
func main() {
app := mizu.New()
app.Get("/api/hello", handleHello)
build, _ := fs.Sub(buildFS, "build")
app.Use(frontend.WithFS(build))
app.Listen(":3000")
}
```
## Common Additions
### Add Router
```bash theme={null}
# React
npm install react-router-dom
# Vue
npm install vue-router
```
### Add State Management
```bash theme={null}
# React
npm install zustand
# Vue
npm install pinia
```
### Add UI Library
```bash theme={null}
# Any framework
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```
## Troubleshooting
### HMR Not Working
Add to Vite config:
```ts theme={null}
server: {
hmr: {
clientPort: 3000, // Your Mizu port
host: 'localhost',
},
}
```
### Assets Not Loading
Ensure base URL is correct:
```ts theme={null}
// vite.config.ts
export default {
base: '/', // Or '/app/' if using prefix
}
```
### Build Not Found
Check embed path matches build output:
```go theme={null}
//go:embed all:dist // Must match vite outDir
var distFS embed.FS
```
## Next Steps
Use ready-made templates instead
All configuration options
Development workflow