---
name: step-05-frontend
description: Generate frontend code using MCP tools (component, API client, routes, i18n)
prev_step: steps/step-04-backend.md
next_step: steps/step-06-migration.md
---

# Step 5: Frontend Generation

## MANDATORY EXECUTION RULES

- ALWAYS use MCP tools for frontend generation
- ALWAYS generate i18n for 4 languages (fr, en, it, de)
- ALWAYS use nested routes (not flat)
- YOU ARE AN ORCHESTRATOR calling MCP, not a generator

## YOUR TASK

Use MCP tools to generate:
1. React component (scaffold_extension type: component)
2. TypeScript API client (scaffold_api_client)
3. Route configuration (scaffold_routes)
4. i18n files (scaffold_translations for UI)

---

## AVAILABLE STATE

From previous steps:

| Variable | Description |
|----------|-------------|
| `{full_path}` | Complete navigation path (navRoute) |
| `{entity_name}` | PascalCase entity name |
| `{entity_code}` | kebab-case code |
| `{labels}` | Object with fr, en, it, de |
| `{api_route}` | API endpoint path |

---

## EXECUTION SEQUENCE

### 1. Generate React Component

```
Tool: mcp__smartstack__scaffold_extension
Args:
  type: "component"
  name: "{entity_name}"
  options:
    outputPath: "web/src/pages/{context}/{application}/{module}"
    dryRun: false
```

This generates:
- `{EntityName}Page.tsx` - Main page component
- `{EntityName}ListView.tsx` - Reusable list view
- `use{EntityName}.ts` - Custom hook for data

### 2. Generate API Client

```
Tool: mcp__smartstack__scaffold_api_client
Args:
  navRoute: "{full_path}"
  name: "{entity_name}"
  methods: ["getAll", "getById", "create", "update", "delete"]
  options:
    includeTypes: true
    includeHook: true
```

This generates:
- `services/api/{entityCode}Api.ts` - API service
- `types/{entityName}.types.ts` - TypeScript interfaces
- `hooks/use{EntityName}Api.ts` - React Query hook (optional)

### 3. Update Route Configuration

```
Tool: mcp__smartstack__scaffold_routes
Args:
  source: "controllers"
  scope: "all"
  options:
    includeGuards: true
    generateRegistry: true
```

This updates:
- `navRoutes.generated.ts` - Route registry
- `routes.tsx` - React Router configuration

### 4. Generate i18n Files

Create translation files for each language:

```markdown
### French (fr/{entityCode}.json)
```json
{
  "title": "{labels.fr}",
  "subtitle": "Gestion de {labels.fr}",
  "columns": {
    "code": "Code",
    "name": "Nom",
    "createdAt": "Créé le",
    "actions": "Actions"
  },
  "form": {
    "code": "Code",
    "name": "Nom",
    "submit": "Enregistrer",
    "cancel": "Annuler"
  },
  "messages": {
    "created": "{labels.fr} créé avec succès",
    "updated": "{labels.fr} mis à jour avec succès",
    "deleted": "{labels.fr} supprimé avec succès",
    "error": "Une erreur est survenue"
  }
}
```

Repeat for en, it, de with appropriate translations.

### 5. Present Output to User

```markdown
## Frontend Code Generated

### Components
- `pages/{context}/{application}/{module}/{EntityName}Page.tsx`
- `pages/{context}/{application}/{module}/{EntityName}ListView.tsx`
- `hooks/use{EntityName}.ts`

### API Client
- `services/api/{entityCode}Api.ts`
- `types/{entityName}.types.ts`

### Routes
- Updated `navRoutes.generated.ts`
- Updated `routes.tsx` with nested route

### i18n
- `locales/fr/{entityCode}.json`
- `locales/en/{entityCode}.json`
- `locales/it/{entityCode}.json`
- `locales/de/{entityCode}.json`

### Route Configuration
```tsx
// In routes.tsx - NESTED routes (not flat!)
<Route path="{application}">
  <Route index element={<Navigate to="{module}" replace />} />
  <Route path="{module}" element={<{EntityName}Page />} />
</Route>
```
```

---

## ROUTING RULES

**CRITICAL:** SmartStack requires NESTED routes:

```tsx
// ✅ CORRECT - Nested routes
<Route path="sales">
  <Route index element={<Navigate to="products" replace />} />
  <Route path="products" element={<ProductsPage />} />
  <Route path="orders" element={<OrdersPage />} />
</Route>

// ❌ FORBIDDEN - Flat routes (cause redirect issues)
<Route path="sales" element={<Navigate to="products" />} />
<Route path="sales/products" element={<ProductsPage />} />
```

---

## I18N STRUCTURE

All i18n files must follow this structure:

```
locales/
├── fr/
│   └── {entityCode}.json
├── en/
│   └── {entityCode}.json
├── it/
│   └── {entityCode}.json
└── de/
    └── {entityCode}.json
```

---

## SUCCESS METRICS

- React component generated
- API client generated with types
- Routes updated (nested structure)
- i18n files created (4 languages)
- Proceeded to step-06-migration.md

## FAILURE MODES

- Component generation failed (check entity name)
- API client generation failed (check navRoute)
- Route configuration failed (check existing routes)

---

## NEXT STEP

After displaying frontend code, proceed to `./step-06-migration.md`
