> ## 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. # Nuxt > Build Nuxt 3 applications with static generation and Mizu backend. Nuxt is the intuitive Vue framework that provides an amazing developer experience with powerful features like auto-imports, file-based routing, server-side rendering, and static site generation. When using Nuxt with Mizu, you'll leverage Nuxt's **static generation** mode to create a fully static site, while Mizu handles your backend API. ## Why Nuxt with Mizu? Nuxt brings the best of Vue with additional superpowers: **File-based routing** - Create pages by adding files to the `pages/` directory. Routes are automatically generated. **Auto-imports** - Components, composables, and utilities are automatically imported. No more import statements! **Layouts** - Define reusable page layouts that wrap your pages. **Composables** - Vue's Composition API with built-in composables like `useFetch`, `useState`, `useRoute`, and more. **Server Components** - Write components that run on the server (or at build time) for better performance. **Developer Experience** - Hot Module Replacement, TypeScript support, and excellent error messages. ### Nuxt with Mizu vs Standalone Nuxt | Feature | Nuxt + Mizu | Standalone Nuxt | | --------------------- | ------------------------- | ---------------------------- | | **Hosting** | Single Go binary | Node.js server or Cloudflare | | **Backend** | Go handlers | Nuxt server routes | | **Deployment** | Any server with Go | Node.js required | | **SSR** | ❌ No (SPA mode) | ✅ Yes | | **Static Generation** | ✅ Yes (SPA) | ✅ Yes (SSG) | | **API Routes** | Go backend | Nuxt server routes | | **Performance** | ⚡ Very fast (Go) | ⚡ Fast (Node.js) | | **Type Safety** | Backend: Go, Frontend: TS | Full-stack TypeScript | **When to use Nuxt with Mizu:** * You want Nuxt's DX (auto-imports, composables, file-based routing) * You prefer Go for backend APIs * You want a single binary deployment * You're building an SPA or static site **When to use standalone Nuxt:** * You need full SSR (server-side rendering at request time) * You want Nuxt server routes and middleware * You prefer Node.js for everything * You need Nuxt's full-stack features (server components, API routes) ### Nuxt vs Vue with Vite | Feature | Nuxt | Vue + Vite | | ------------------------ | -------------- | ---------------------- | | **File-based routing** | ✅ Built-in | ⚠️ Manual (vue-router) | | **Auto-imports** | ✅ Yes | ❌ No | | **Layouts** | ✅ Built-in | ⚠️ Manual | | **Built-in composables** | ✅ Many | ⚠️ Few | | **Bundle size** | ⚠️ Larger | ✅ Smaller | | **Setup complexity** | ⚠️ More | ✅ Less | | **Flexibility** | ⚠️ Opinionated | ✅ Very flexible | | **Best for** | Apps, sites | Libraries, simple apps | ## How Nuxt Works with Mizu When you build Nuxt in SPA mode for Mizu: ``` Build Process ↓ ┌─────────────────────────────┐ │ Nuxt analyzes pages/ │ │ - Creates routes │ │ - Auto-imports components │ └─────────────┬───────────────┘ ↓ ┌─────────────────────────────┐ │ Vite builds application │ │ - Bundles Vue components │ │ - Optimizes assets │ │ - Generates chunks │ └─────────────┬───────────────┘ ↓ ┌─────────────────────────────┐ │ Outputs SPA files │ │ - dist/ │ │ ├── index.html │ │ ├── _nuxt/ │ │ │ └── *.js │ │ └── assets/ │ └─────────────────────────────┘ ``` **At runtime:** 1. Mizu serves the pre-built files 2. Browser loads `index.html` + JavaScript 3. Vue takes over and renders the app 4. Client-side routing handles navigation 5. API calls go to Mizu backend (Go) ## Quick Start Create a new Nuxt project with the CLI: ```bash theme={null} mizu new ./my-nuxt-app --template frontend/nuxt cd my-nuxt-app make dev ``` Visit `http://localhost:3000` to see your app! ## Project Structure ``` my-nuxt-app/ ├── cmd/ │ └── server/ │ └── main.go # Go entry point ├── app/ │ └── server/ │ ├── app.go # Mizu app configuration │ ├── config.go # Server configuration │ └── routes.go # API routes (Go) ├── frontend/ # Nuxt application │ ├── pages/ # File-based routes │ │ ├── index.vue # Home page (/) │ │ ├── about.vue # About page (/about) │ │ └── users/ │ │ ├── index.vue # Users list (/users) │ │ └── [id].vue # User detail (/users/123) │ ├── components/ # Auto-imported components │ │ ├── TheHeader.vue │ │ ├── TheFooter.vue │ │ └── UserCard.vue │ ├── composables/ # Auto-imported composables │ │ ├── useUsers.ts │ │ └── useAuth.ts │ ├── layouts/ # Page layouts │ │ ├── default.vue # Default layout │ │ └── auth.vue # Auth layout │ ├── public/ # Static assets │ │ └── images/ │ ├── assets/ # Assets to be processed │ │ ├── css/ │ │ └── images/ │ ├── plugins/ # Vue plugins │ │ └── api.ts │ ├── middleware/ # Route middleware │ │ └── auth.ts │ ├── app.vue # Root component │ ├── nuxt.config.ts # Nuxt configuration │ ├── package.json │ └── tsconfig.json ├── dist/ # Built files (after build) ├── go.mod └── Makefile ``` ## Configuration ### Nuxt Configuration Configure Nuxt for SPA mode and Mizu integration: #### `frontend/nuxt.config.ts` ```ts theme={null} // https://nuxt.com/docs/api/configuration/nuxt-config export default defineNuxtConfig({ // SPA mode (no SSR) ssr: false, // Development tools devtools: { enabled: true }, // TypeScript configuration typescript: { strict: true, typeCheck: true }, // Build output configuration nitro: { output: { dir: '../dist', // Output to dist/ at project root publicDir: '../dist' // Public directory } }, // Vite configuration vite: { server: { port: 5173, strictPort: true, hmr: { clientPort: 3000 // Mizu's port for HMR } } }, // Auto-import configuration components: { dirs: [ '~/components', // Auto-import from components/ '~/components/common', // Sub-directories too '~/components/forms' ] }, // CSS css: ['~/assets/css/main.css'], // Modules (add as needed) modules: [ // '@pinia/nuxt', // State management // '@nuxtjs/tailwindcss', // Tailwind CSS ] }) ``` **Configuration explained:** * **ssr: false** - Runs Nuxt in SPA mode (no server-side rendering) * **nitro.output** - Outputs built files to `dist/` directory * **vite.server.hmr.clientPort** - HMR through Mizu's proxy on port 3000 * **components.dirs** - Directories to auto-import components from ### Backend Configuration #### `app/server/app.go` ```go theme={null} package server import ( "embed" "io/fs" "github.com/go-mizu/mizu" "github.com/go-mizu/mizu/frontend" ) // Embed the Nuxt build output //go:embed all:../../dist var distFS embed.FS func New(cfg *Config) *mizu.App { app := mizu.New() // API routes come first setupRoutes(app) // Extract 'dist' subdirectory from embedded FS dist, _ := fs.Sub(distFS, "dist") // Frontend middleware (handles all non-API routes) app.Use(frontend.WithOptions(frontend.Options{ Mode: frontend.ModeAuto, // Auto-detect dev/prod FS: dist, // Embedded dist files Root: "./dist", // Fallback to filesystem DevServer: "http://localhost:" + cfg.DevPort, // Nuxt dev server IgnorePaths: []string{"/api"}, // Don't proxy /api })) return app } ``` #### `app/server/routes.go` ```go theme={null} package server import "github.com/go-mizu/mizu" func setupRoutes(app *mizu.App) { // User API app.Get("/api/users", handleUsers) app.Post("/api/users", createUser) app.Get("/api/users/{id}", getUser) app.Put("/api/users/{id}", updateUser) app.Delete("/api/users/{id}", deleteUser) // Posts API app.Get("/api/posts", handlePosts) app.Get("/api/posts/{id}", getPost) } func handleUsers(c *mizu.Ctx) error { users := []map[string]any{ {"id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin"}, {"id": 2, "name": "Bob", "email": "bob@example.com", "role": "user"}, {"id": 3, "name": "Charlie", "email": "charlie@example.com", "role": "user"}, } return c.JSON(200, users) } func getUser(c *mizu.Ctx) error { id := c.Param("id") user := map[string]any{ "id": id, "name": "User " + id, "email": "user" + id + "@example.com", "role": "user", } return c.JSON(200, user) } func createUser(c *mizu.Ctx) error { var user map[string]any if err := c.BodyJSON(&user); err != nil { return c.JSON(400, map[string]string{"error": "Invalid JSON"}) } // Add ID (in real app, use database) user["id"] = 4 return c.JSON(201, user) } ``` ## File-Based Routing Nuxt automatically generates routes based on files in the `pages/` directory. ### Basic Routes ``` pages/ ├── index.vue → / ├── about.vue → /about ├── contact.vue → /contact └── blog.vue → /blog ``` ### Nested Routes ``` pages/ ├── users/ │ ├── index.vue → /users │ └── profile.vue → /users/profile └── blog/ ├── index.vue → /blog └── [slug].vue → /blog/:slug ``` ### Dynamic Routes Use square brackets for dynamic segments: ``` pages/ ├── users/ │ └── [id].vue → /users/:id ├── posts/ │ └── [slug].vue → /posts/:slug └── products/ └── [category]/ └── [id].vue → /products/:category/:id ``` ### Route Parameters Access route parameters with `useRoute()`: #### `pages/users/[id].vue` ```vue theme={null} ``` ### Catch-All Routes Create a catch-all route with `[...slug].vue`: ``` pages/ └── blog/ └── [...slug].vue → /blog/* (any path) ``` ```vue theme={null} ``` ## Auto-Imports One of Nuxt's killer features is auto-imports. No more import statements! ### What Gets Auto-Imported? **Vue APIs:** ```vue theme={null} ``` **Components:** ```vue theme={null} ``` **Composables:** ```vue theme={null} ``` **Utils:** ```vue theme={null} ``` ### Auto-Import Configuration Control what gets auto-imported in `nuxt.config.ts`: ```ts theme={null} export default defineNuxtConfig({ // Disable auto-imports (not recommended) imports: { autoImport: false }, // Or customize which directories imports: { dirs: [ 'composables', // Default 'composables/**', // All subdirectories 'utils', 'stores' ] } }) ``` ### TypeScript Support Nuxt automatically generates TypeScript types for auto-imports: ```ts theme={null} // .nuxt/imports.d.ts (auto-generated) export const ref: typeof import('vue')['ref'] export const computed: typeof import('vue')['computed'] export const useRoute: typeof import('#app')['useRoute'] // ... many more ``` Your IDE will have full autocomplete and type checking! ## Layouts Layouts wrap your pages with common UI elements. ### Default Layout Create a default layout that wraps all pages: #### `layouts/default.vue` ```vue theme={null} ``` ### Custom Layouts Create additional layouts for different page types: #### `layouts/auth.vue` ```vue theme={null} ``` ### Using Layouts in Pages Specify which layout to use with `definePageMeta`: ```vue theme={null} ``` ### No Layout Disable layout for a page: ```vue theme={null} ``` ## Built-in Composables Nuxt provides powerful composables for common tasks. ### useFetch Fetch data from an API: ```vue theme={null} ``` ### useAsyncData More control over async data fetching: ```vue theme={null} ``` ### useState Shared state across components: ```ts theme={null} // composables/useCounter.ts export const useCounter = () => { // State is shared across all components using this composable const count = useState('counter', () => 0) const increment = () => count.value++ const decrement = () => count.value-- return { count, increment, decrement } } ``` ```vue theme={null} ``` ### useRoute and useRouter Access routing information: ```vue theme={null} ``` ### useCookie Work with cookies: ```vue theme={null} ``` ### useHead Manage document head: ```vue theme={null} ``` ## Custom Composables Create reusable composables for your app logic: ### User Management Composable ```ts theme={null} // composables/useUsers.ts export const useUsers = () => { const users = useState('users', () => []) const loading = ref(false) const error = ref(null) const fetchUsers = async () => { loading.value = true error.value = null try { const { data } = await useFetch('/api/users') users.value = data.value || [] } catch (e) { error.value = e as Error } finally { loading.value = false } } const addUser = async (user: Omit) => { const { data } = await useFetch('/api/users', { method: 'POST', body: user }) if (data.value) { users.value.push(data.value) } } const deleteUser = async (id: number) => { await useFetch(`/api/users/${id}`, { method: 'DELETE' }) users.value = users.value.filter(u => u.id !== id) } return { users: readonly(users), loading: readonly(loading), error: readonly(error), fetchUsers, addUser, deleteUser } } ``` Usage: ```vue theme={null} ``` ### Authentication Composable ```ts theme={null} // composables/useAuth.ts interface User { id: number name: string email: string } export const useAuth = () => { const user = useState('auth-user', () => null) const token = useCookie('auth-token') const login = async (email: string, password: string) => { const { data, error } = await useFetch('/api/auth/login', { method: 'POST', body: { email, password } }) if (data.value) { user.value = data.value.user token.value = data.value.token } return { data, error } } const logout = async () => { await useFetch('/api/auth/logout', { method: 'POST' }) user.value = null token.value = null } const fetchUser = async () => { if (!token.value) return const { data } = await useFetch('/api/auth/me', { headers: { Authorization: `Bearer ${token.value}` } }) user.value = data.value } const isAuthenticated = computed(() => !!user.value) return { user: readonly(user), isAuthenticated, login, logout, fetchUser } } ``` ## Middleware Route middleware runs before rendering a page. ### Global Middleware Runs on every route: ```ts theme={null} // middleware/auth.global.ts export default defineNuxtRouteMiddleware((to, from) => { const { isAuthenticated } = useAuth() // Protect /dashboard routes if (to.path.startsWith('/dashboard') && !isAuthenticated.value) { return navigateTo('/login') } }) ``` ### Named Middleware Runs only when specified: ```ts theme={null} // middleware/admin.ts export default defineNuxtRouteMiddleware((to, from) => { const { user } = useAuth() if (user.value?.role !== 'admin') { return navigateTo('/') } }) ``` Use in pages: ```vue theme={null} ``` ### Multiple Middleware ```vue theme={null} ``` ## Components ### Auto-Imported Components Components in `components/` are automatically available: ``` components/ ├── TheHeader.vue → ├── TheFooter.vue → ├── UserCard.vue → └── common/ └── Button.vue → ``` ```vue theme={null} ``` ### Component Example ```vue theme={null} ``` ## State Management with Pinia For complex state, use Pinia: ```bash theme={null} cd frontend npm install pinia @pinia/nuxt ``` Add to `nuxt.config.ts`: ```ts theme={null} export default defineNuxtConfig({ modules: ['@pinia/nuxt'] }) ``` Create a store: ```ts theme={null} // stores/users.ts import { defineStore } from 'pinia' interface User { id: number name: string email: string role: string } export const useUserStore = defineStore('users', () => { const users = ref([]) const loading = ref(false) const selectedUser = ref(null) const userCount = computed(() => users.value.length) const adminUsers = computed(() => users.value.filter(u => u.role === 'admin') ) async function fetchUsers() { loading.value = true try { const { data } = await useFetch('/api/users') users.value = data.value || [] } finally { loading.value = false } } async function addUser(user: Omit) { const { data } = await useFetch('/api/users', { method: 'POST', body: user }) if (data.value) { users.value.push(data.value) } } async function updateUser(id: number, updates: Partial) { const { data } = await useFetch(`/api/users/${id}`, { method: 'PUT', body: updates }) if (data.value) { const index = users.value.findIndex(u => u.id === id) if (index !== -1) { users.value[index] = data.value } } } async function deleteUser(id: number) { await useFetch(`/api/users/${id}`, { method: 'DELETE' }) users.value = users.value.filter(u => u.id !== id) } function selectUser(user: User) { selectedUser.value = user } function clearSelection() { selectedUser.value = null } return { users, loading, selectedUser, userCount, adminUsers, fetchUsers, addUser, updateUser, deleteUser, selectUser, clearSelection } }) ``` Use in components: ```vue theme={null} ``` ## Styling ### Scoped Styles Use scoped styles by default: ```vue theme={null} ``` ### Global Styles Create global CSS: ```css theme={null} /* assets/css/main.css */ * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; line-height: 1.6; color: #333; } ``` Import in `nuxt.config.ts`: ```ts theme={null} export default defineNuxtConfig({ css: ['~/assets/css/main.css'] }) ``` ### Tailwind CSS Install Tailwind module: ```bash theme={null} cd frontend npm install -D @nuxtjs/tailwindcss ``` Add to `nuxt.config.ts`: ```ts theme={null} export default defineNuxtConfig({ modules: ['@nuxtjs/tailwindcss'] }) ``` Use in components: ```vue theme={null} ``` ### CSS Modules ```vue theme={null} ``` ## Plugins Create Vue plugins: ```ts theme={null} // plugins/api.ts export default defineNuxtPlugin(() => { const api = { get: (url: string) => $fetch(url), post: (url: string, data: any) => $fetch(url, { method: 'POST', body: data }), put: (url: string, data: any) => $fetch(url, { method: 'PUT', body: data }), delete: (url: string) => $fetch(url, { method: 'DELETE' }) } return { provide: { api } } }) ``` Use in components: ```vue theme={null} ``` ## Development Workflow ### Starting Development ```bash theme={null} # Option 1: Use Makefile (recommended) make dev # Option 2: Manual (two terminals) # Terminal 1: Nuxt dev server cd frontend npm run dev # Starts on http://localhost:5173 # Terminal 2: Mizu server go run cmd/server/main.go # Starts on http://localhost:3000 ``` **How it works:** 1. Nuxt runs dev server on port 5173 2. Mizu runs on port 3000 3. Requests to port 3000 proxy to Nuxt (except `/api`) 4. Visit `http://localhost:3000` 5. HMR works through proxy ### Making Changes **Frontend changes:** * Edit files in `frontend/` * Nuxt HMR updates browser instantly * Components, pages, composables auto-reload **Backend changes:** * Edit Go files * Restart Mizu server * Or use `air` for auto-reload ```bash theme={null} go install github.com/cosmtrek/air@latest air ``` ## Building for Production Build the application: ```bash theme={null} make build ``` This runs: 1. `cd frontend && npm run build` - Nuxt build 2. `go build` - Go binary with embedded frontend ### Build Output ``` dist/ ├── index.html # SPA entry point ├── _nuxt/ # Nuxt assets │ ├── entry.abc123.js # Main bundle │ ├── *.chunk.js # Code split chunks │ └── *.css # Styles └── assets/ # Static assets ``` ### Running in Production ```bash theme={null} MIZU_ENV=production ./bin/server ``` ## TypeScript Nuxt has excellent TypeScript support: ### Typed Composables ```ts theme={null} // composables/useUsers.ts import type { User } from '~/types' export const useUsers = () => { const users = useState('users', () => []) const fetchUsers = async (): Promise => { const { data } = await useFetch('/api/users') users.value = data.value || [] } return { users: readonly(users), fetchUsers } } ``` ### Typed Components ```vue theme={null} ``` ### Auto-Generated Types Nuxt generates types automatically: ```ts theme={null} // .nuxt/types/middleware.d.ts declare module '#app' { interface PageMeta { middleware?: 'auth' | 'admin' | 'guest' } } ``` ## Troubleshooting ### HMR Not Working **Symptom:** Changes don't appear in browser **Cause:** HMR WebSocket not connecting through proxy **Solution:** Check `vite.server.hmr.clientPort` in `nuxt.config.ts`: ```ts theme={null} export default defineNuxtConfig({ vite: { server: { hmr: { clientPort: 3000 // Must match Mizu port } } } }) ``` *** ### Hydration Mismatch **Error:** ``` [Vue warn]: Hydration node mismatch ``` **Cause:** Server-rendered HTML doesn't match client **Solution:** Wrap dynamic content in ``: ```vue theme={null} ``` *** ### Auto-Import Not Working **Symptom:** Component/composable not found **Solution 1:** Check file naming (must be in correct directory) ``` components/ └── UserCard.vue ✅ Works composables/ └── useUsers.ts ✅ Works ``` **Solution 2:** Restart dev server: ```bash theme={null} npm run dev ``` **Solution 3:** Check `.nuxt/` was generated: ```bash theme={null} rm -rf frontend/.nuxt npm run dev ``` *** ### 404 on Refresh in SPA Mode **Symptom:** Page works initially, but refreshing gives 404 **Cause:** SPA fallback not configured **Solution:** Mizu automatically handles this, but ensure: ```go theme={null} app.Use(frontend.WithOptions(frontend.Options{ Mode: frontend.ModeAuto, Root: "./dist", Index: "index.html", // Important for SPA fallback })) ``` *** ### Build Fails: "Cannot find module" **Error:** ``` Cannot find module '@/components/Header' ``` **Cause:** Path alias not configured **Solution:** Check `tsconfig.json`: ```json theme={null} { "extends": "./.nuxt/tsconfig.json", "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./*"], "~/*": ["./*"] } } } ``` ## Real-World Example: Task Management App Complete example showing Nuxt features: ### Backend ```go theme={null} // app/server/routes.go type Task struct { ID int `json:"id"` Title string `json:"title"` Completed bool `json:"completed"` UserID int `json:"user_id"` } var tasks = []Task{ {ID: 1, Title: "Learn Nuxt", Completed: true, UserID: 1}, {ID: 2, Title: "Build App", Completed: false, UserID: 1}, } func setupRoutes(app *mizu.App) { app.Get("/api/tasks", handleTasks) app.Post("/api/tasks", createTask) app.Put("/api/tasks/{id}", updateTask) app.Delete("/api/tasks/{id}", deleteTask) } func handleTasks(c *mizu.Ctx) error { return c.JSON(200, tasks) } func createTask(c *mizu.Ctx) error { var task Task if err := c.BodyJSON(&task); err != nil { return c.JSON(400, map[string]string{"error": "Invalid JSON"}) } task.ID = len(tasks) + 1 tasks = append(tasks, task) return c.JSON(201, task) } ``` ### Store ```ts theme={null} // stores/tasks.ts import { defineStore } from 'pinia' interface Task { id: number title: string completed: boolean user_id: number } export const useTaskStore = defineStore('tasks', () => { const tasks = ref([]) const loading = ref(false) const filter = ref<'all' | 'active' | 'completed'>('all') const filteredTasks = computed(() => { switch (filter.value) { case 'active': return tasks.value.filter(t => !t.completed) case 'completed': return tasks.value.filter(t => t.completed) default: return tasks.value } }) const activeCount = computed(() => tasks.value.filter(t => !t.completed).length ) async function fetchTasks() { loading.value = true const { data } = await useFetch('/api/tasks') tasks.value = data.value || [] loading.value = false } async function addTask(title: string) { const { data } = await useFetch('/api/tasks', { method: 'POST', body: { title, completed: false, user_id: 1 } }) if (data.value) { tasks.value.push(data.value) } } async function toggleTask(id: number) { const task = tasks.value.find(t => t.id === id) if (!task) return const { data } = await useFetch(`/api/tasks/${id}`, { method: 'PUT', body: { ...task, completed: !task.completed } }) if (data.value) { const index = tasks.value.findIndex(t => t.id === id) tasks.value[index] = data.value } } async function deleteTask(id: number) { await useFetch(`/api/tasks/${id}`, { method: 'DELETE' }) tasks.value = tasks.value.filter(t => t.id !== id) } return { tasks: readonly(tasks), loading: readonly(loading), filter, filteredTasks, activeCount, fetchTasks, addTask, toggleTask, deleteTask } }) ``` ### Page ```vue theme={null} ``` ### Components ```vue theme={null} ``` ```vue theme={null} ``` ## When to Choose Nuxt ### Choose Nuxt When: ✅ You want file-based routing with zero configuration ✅ You love Vue and want enhanced DX ✅ Auto-imports appeal to you (less boilerplate) ✅ You want built-in layouts and middleware ✅ You're building a content-heavy site or app ✅ Your team values convention over configuration ✅ You want powerful built-in composables ### Choose Vanilla Vue When: ✅ You want complete control over setup ✅ You prefer explicit imports ✅ Bundle size is critical (Nuxt adds overhead) ✅ You're building a library ✅ You don't need file-based routing ✅ You prefer configuration freedom ## Next Steps Compare with vanilla Vue + Vite React equivalent of Nuxt Official Vue state management Official Nuxt documentation