Troubleshooting

​

Dev Server Issues

​

Can’t Connect to Dev Server

1. Check dev server is running:
   cd frontend
   npm run dev
   
2. Check port matches:
   // Backend
   DevServer: "http://localhost:5173",
   
   // Frontend vite.config.ts
   server: { port: 5173 }
   
3. Check firewall:
   # macOS
   sudo pfctl -d
   

​

HMR Not Working

1. Configure HMR port:
   // vite.config.ts
   server: {
     hmr: {
       clientPort: 3000,  // Mizu server port
     },
   }
   
2. Check WebSocket connection:
   • Open browser DevTools → Network → WS
   • Should see WebSocket connection to ws://localhost:3000
3. Clear browser cache:
   • Hard refresh: Cmd/Ctrl + Shift + R

​

Port Already in Use

1. Kill process:
   # macOS/Linux
   lsof -ti:3000 | xargs kill -9
   
   # Windows
   netstat -ano | findstr :3000
   taskkill /PID <PID> /F
   
2. Change port:
   // config.go
   Port: "3001",
   

​

Build Issues

​

Build Fails

1. Clear cache:
   rm -rf node_modules package-lock.json
   npm install
   
2. Clear Vite cache:
   rm -rf node_modules/.vite
   
3. Check Node version:
   node --version  # Should be 18+
   

​

Assets Not Found After Build

1. Check embed path:
   //go:embed all:dist  # Must match build outDir
   var distFS embed.FS
   
   dist, _ := fs.Sub(distFS, "dist")  # Must match embed path
   
2. Check Vite base:
   // vite.config.ts
   export default {
     base: '/',  # Or '/app/' if using prefix
   }
   
3. Rebuild:
   cd frontend && npm run build
   go build
   

​

Routing Issues

​

404 on Page Refresh

// Check IgnorePaths doesn't block your routes
app.Use(frontend.WithOptions(frontend.Options{
    IgnorePaths: []string{"/api"},  // Only API, not frontend routes
}))

​

API Routes Return HTML

1. Define API routes before frontend middleware:
   // ✅ Correct order
   app.Get("/api/users", handleUsers)  // First
   app.Use(frontend.New("./dist"))     // After
   
   // ❌ Wrong order
   app.Use(frontend.New("./dist"))     // Frontend catches everything
   app.Get("/api/users", handleUsers)  // Never reached
   
2. Check IgnorePaths:
   app.Use(frontend.WithOptions(frontend.Options{
       IgnorePaths: []string{"/api"},  // API routes bypass frontend
   }))
   

​

CORS Issues

​

CORS Errors in Development

1. Dev server is proxying correctly:
   // vite.config.ts
   server: {
     proxy: {
       '/api': 'http://localhost:3000',
     },
   }
   
2. Or use Mizu’s proxy: Don’t configure Vite proxy, let Mizu handle it:
   app.Use(frontend.Dev("http://localhost:5173"))
   

​

CORS Errors in Production

import "github.com/go-mizu/mizu/middlewares/cors"

app.Use(cors.WithOptions(cors.Options{
    AllowedOrigins: []string{"https://yourdomain.com"},
    AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowedHeaders: []string{"Content-Type", "Authorization"},
}))

​

TypeScript Issues

​

Module Not Found

1. Check import path:
   // ❌ Wrong
   import Component from './Component'
   
   // ✅ Correct (include extension)
   import Component from './Component.tsx'
   
2. Configure path aliases:
   // vite.config.ts
   export default {
     resolve: {
       alias: {
         '@': path.resolve(__dirname, './src'),
       },
     },
   }
   
   // tsconfig.json
   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

​

Performance Issues

​

Slow Initial Load

1. Enable code splitting:
   const About = lazy(() => import('./pages/About'))
   
2. Analyze bundle:
   npm run build
   # Check bundle sizes in output
   
3. Reduce dependencies:
   # Remove unused packages
   npm prune
   

​

Slow HMR

1. Optimize Vite config:
   export default {
     optimizeDeps: {
       include: ['react', 'react-dom'],  // Pre-bundle deps
     },
   }
   
2. Reduce file watchers:
   • Close unused files in editor
   • Exclude node_modules from watchers

​

Environment Issues

​

Environment Variables Not Working

1. Check prefix:
   # ❌ Won't work
   API_URL=http://localhost:3000
   
   # ✅ Must have VITE_ prefix
   VITE_API_URL=http://localhost:3000
   
2. Restart dev server: Environment variables are loaded at startup
3. Check file name:
   .env                 # All modes
   .env.local           # Local overrides (gitignored)
   .env.development     # Development only
   .env.production      # Production only
   

​

Debugging Tips

​

Enable Debug Logging

import "github.com/go-mizu/mizu/middlewares/logger"

app.Use(logger.New())  // Logs all requests
app.Use(frontend.Dev("http://localhost:5173"))

​

Check Network Tab

• Filter by XHR to see API calls
• Check request/response
• Verify status codes

​

Check Console

• Look for JavaScript errors
• Check for failed requests
• Verify HMR messages

​

Verify Build Output

cd dist
ls -lh  # Check files exist
file index.html  # Should be HTML
cat index.html  # Check content

​

Getting Help

1. Check GitHub Issues
2. Ask in Discord
3. Review examples

​

Next Steps