# Frontend: Route Wiring in App.tsx

> Referenced from `steps/step-05-frontend.md` — Detailed route wiring patterns and verification.

---

## Step 4: Wire Routes to App.tsx (BLOCKING)

**CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.

After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.

---

## Step 4a: Import Page Components

At the top of App.tsx:

```tsx
import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
// Or lazy-loaded:
const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{EntityName}Page'));
```

---

## Step 4b: Detect App.tsx Routing Pattern

Read App.tsx and detect which pattern is used:

### Pattern A: applicationRoutes Object

**If App.tsx contains:** `applicationRoutes: ApplicationRouteExtensions`

→ Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)

```tsx
const applicationRoutes: ApplicationRouteExtensions = {
  'human-resources': [
    // existing routes...
    { path: '{module_kebab}', element: <{EntityName}ListPage /> },
    { path: '{module_kebab}/new', element: <Create{EntityName}Page /> },
    { path: '{module_kebab}/:id', element: <{EntityName}DetailPage /> },
    { path: '{module_kebab}/:id/edit', element: <Create{EntityName}Page /> },
  ],
};
```

Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.

### Pattern B: JSX Routes

**If App.tsx contains:** `<Route path="/{application}" element={<{Layout} />}>`

→ Insert `<Route>` children inside the Layout wrapper:

```tsx
<Route path="/human-resources" element={<AppLayout />}>
  {/* ... existing routes ... */}
  <Route path="{module_kebab}" element={<{EntityName}Page />} />
</Route>
```

**ALSO add the same routes inside the tenant-prefixed block:**

Find `<Route path="/t/:slug">` and add the **same route entries** there.

---

## Step 4c: Application-to-Layout Mapping

| Application prefix | Layout Component | Route path |
|---------|------------------|------------|
| `administration.*` | `AppLayout` | `/administration` |
| `*` (business apps) | `AppLayout` | `/{application}` |
| `myspace.*` | `AppLayout` | `/myspace` |

---

## Step 4d: Verify Wiring

```
Tool: mcp__smartstack__validate_frontend_routes
Args:
  scope: "routes"
```

If `appWiring.issues` is not empty, fix the wiring before proceeding.

---

## Forbidden Patterns (BOTH patterns)

- Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
- Adding routes OUTSIDE the Layout wrapper (shell will not render)
- Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)

---

## Verification Checklist

- [ ] Routes are inside the AppLayout wrapper
- [ ] Routes use NESTED structure (not flat)
- [ ] Application kebab-case matches navigation seed data
- [ ] Both standard and tenant-prefixed blocks have routes (if using Pattern B)
- [ ] Page components are imported at top of App.tsx
- [ ] `mcp__smartstack__validate_frontend_routes` returns no issues
