name	frontend-development
description	Guidelines for Wails 3 GUI frontend development with React and TypeScript. Use when working on frontend/, UI components, or Wails bindings.
user-invocable	false

Frontend Development Guidelines

Guidelines for developing the Wails 3 GUI frontend of mcpd, built with React and TypeScript.

Prerequisites

Node.js (version specified in frontend/package.json)
Wails 3.0.0-alpha.53
Go 1.25+ (for Wails bindings generation)

Development Commands

Wails GUI Development

# Generate TypeScript bindings for Go services
make wails-bindings

# Run Wails in development mode (hot reload)
make wails-dev

# Build Wails application
make wails-build

# Package Wails application for distribution
make wails-package

Frontend Structure

The frontend is located in the frontend/ directory and follows standard React/TypeScript conventions.

Key Directories:

frontend/src/: Source code
- components/: Reusable UI components
- routes/: Page components and routing
- modules/: Feature modules with hooks and utilities
- bindings/: Auto-generated TypeScript bindings from Go services
frontend/public/: Static assets

Working with Wails Bindings

Generating Bindings

Whenever you modify Go service methods in internal/ui/, regenerate TypeScript bindings:

make wails-bindings

This creates TypeScript interfaces and functions in frontend/src/bindings/ that match your Go service methods.

Using Bindings in Frontend

Import and use the generated bindings in your React components:

import { ServiceMethod } from '@/bindings/...'

// Use in component
const result = await ServiceMethod(params)

Development Workflow

Modify Go Services: Add or update methods in internal/ui/
Regenerate Bindings: Run make wails-bindings
Update Frontend: Use the new bindings in your React components
Test in Dev Mode: Run make wails-dev for hot reload
Build: Run make wails-build when ready

Frontend-Specific Guidelines

For detailed React/TypeScript frontend-specific guidance, see frontend/CLAUDE.md.

Integration with Backend

The Wails bridge layer (internal/ui/) exposes core functionality to the GUI:

Service methods in internal/ui/ become callable from frontend
TypeScript bindings provide type-safe access to Go functions
Wails handles serialization/deserialization automatically
Frontend can access all core control plane features through bindings

Common Tasks

Adding a New UI Feature

Implement Go service methods in internal/ui/
Regenerate TypeScript bindings: make wails-bindings
Create React components in frontend/src/
Use bindings to call Go services: import { Method } from '@/bindings/...'
Test in development mode: make wails-dev

Updating Existing Features

Modify Go service methods in internal/ui/ if needed
Regenerate bindings if Go signatures changed: make wails-bindings
Update React components in frontend/src/
Test changes: make wails-dev

Debugging

Use browser DevTools in Wails dev mode
Check console for TypeScript/React errors
Verify bindings are up-to-date if Go methods changed
Check internal/ui/ for Go-side errors

Best Practices

Always regenerate bindings after modifying Go services
Keep UI logic in React components, business logic in Go services
Use TypeScript types from bindings for type safety
Follow React best practices (hooks, component composition, etc.)
See frontend/CLAUDE.md for detailed frontend conventions