golid / rules

---
description: Guidance for splitting large route files into maintainable pieces
alwaysApply: false
---

# Refactoring Large Route Files

> **Thesis:** Split route files at 600+ lines. Extracted components receive data via props and callbacks — they never import the parent's signals.

## When to Split

Any route file **over 600 lines** should be split. Signs it's time:
- Multiple distinct UI sections (KPI bar, table, modal, form)
- Multiple modal components with their own state
- Helper functions / sub-components that don't need the page's signals

## How to Split

### Co-located Components

Create a `_components/` directory next to the route file:

```
routes/(private)/items/
├── index.tsx              ← Page (signals, data fetching, layout)
├── _components/
│   ├── ItemCard.tsx        ← Presentational (receives props)
│   ├── CreateItemModal.tsx ← Modal with own form state
│   └── ItemDetailModal.tsx ← Detail modal with tabs
```

The `_` prefix tells SolidStart this is NOT a route — it's a co-located module.

### What Goes Where

**Parent route file keeps:**
- Data fetching (`onMount`, `createSignal`, `createEffect`)
- Page-level signals (loading, error, data, filters, pagination)
- `alive` guard and `onCleanup`
- Layout structure (`Switch/Match` for content states)
- Signal-driven modal open/close logic

**Extracted components receive:**
- Data via **props** (not by importing shared signals)
- Callbacks via **props** (`onSave`, `onClose`, `onDelete`)
- They are **presentational** — they render what they're given

### Example Split

Before (800-line `items/index.tsx`):
```tsx
export default function ItemsPage() {
  // 50 lines of signals + fetching
  // 100 lines of ItemCard component
  // 200 lines of CreateItemModal
  // 300 lines of ItemDetailModal
  // 150 lines of page layout
}
```

After:
```tsx
// items/index.tsx (200 lines)
import { ItemCard } from "./_components/ItemCard";
import { CreateItemModal } from "./_components/CreateItemModal";
import { ItemDetailModal } from "./_components/ItemDetailModal";

export default function ItemsPage() {
  // signals + fetching + layout
  // passes data to components via props
}
```

```tsx
// items/_components/ItemCard.tsx (100 lines)
export function ItemCard(props: { item: Item; onClick: () => void }) {
  // pure presentational
}
```

## Rules

1. **Props, not imports** — extracted components get data via props, never import the parent's signals
2. **Callbacks, not mutations** — extracted components call `props.onSave()`, not `setData()` directly
3. **Own state is OK** — modals can have their own form signals (`title`, `description`, `saving`)
4. **Alive guards stay in parent** — the parent manages the component lifecycle
5. **Don't over-split** — a 400-line file with one modal is fine. Split when there are 3+ distinct UI sections.

## Dedup Gotcha: "Use the Existing Helper" Hides Behavior Changes

When splitting a large file reveals duplicated code that already has a centralized version elsewhere, **stop and check whether the duplicates have intentional behavior differences before proposing the migration.** A refactor that swaps `localCheckX(...)` for `sharedCheckX(...)` looks like pure dedup but can silently change auth, validation, or error semantics.

The smoking gun is usually a comment on the shared helper explaining why callers haven't migrated. If you see that comment, the duplication is intentional and the migration is a **product decision**, not a refactor.

**Concrete case:** two callers each have `verifyResourceAccess`-style helpers that look identical but enforce different membership predicates (e.g. owner-only vs any member). A shared helper's doc comment may explicitly say *"replacing caller X is a separate, behavior-changing migration."* A refactor that swaps local checks for the shared helper without reading that comment can silently widen permissions.

### Workflow when you spot duplication

1. **Read the shared helper's doc comment in full.** If it explains why callers haven't migrated, treat that as a hard stop on the migration.
2. **Diff the duplicated functions semantically**, not textually. Same SQL ≠ same authorization. Same validation ≠ same error code.
3. **If behaviors differ:**
   - Scope the dedup to the truly shared part — usually the SQL JOIN, the parsing, or the struct unmarshal. Extract that as a private helper (`loadMatchInfo`, `parseMatchID`).
   - Leave each caller's divergent business logic (auth predicate, error message, side effects) in the caller.
   - State this explicitly in the plan: **"Pure dedup, no auth/behavior surface change."**
4. **If you think the behaviors *should* converge:** that's a product/permissions decision. File a separate ticket, get a product call, then ship the convergence as its own PR — don't smuggle it inside a refactor.

### Anti-rationalization

| Excuse | Counter |
|---|---|
| "The shared helper is strictly more permissive, so swapping is safe" | Strictly more permissive is the textbook definition of a permission widening. That's the change you're not allowed to ship as a refactor. |
| "The doc comment is stale" | The doc comment is the codified intent. If it's stale, ship a separate commit that updates it (with product sign-off) before the migration. |
| "Other callers already use the shared helper" | Those callers were originally written against it. The duplicating callers were written against the narrower predicate on purpose. Different callers can want different policies. |

## Exception: Self-Contained Tabs

When a page is organized as tabs where each tab manages its own data fetching and state (e.g., settings page), tabs can import shared stores directly (like `auth`) instead of receiving data via props. The test: if removing the parent's `onMount` wouldn't break the tab, it's self-contained.

```
settings/
├── index.tsx              ← Shell with Tabs + inline AccountTab (~120 lines)
├── _components/
│   ├── Section.tsx         ← Shared layout component
│   ├── EssentialsTab.tsx   ← Own signals, reads auth directly
│   ├── PortfolioTab.tsx    ← Own onMount, uploads, alive guard
│   ├── NotificationsTab.tsx
│   └── TeamTab.tsx         ← Own data fetching, invite flow
```

This is valid because there's zero cross-tab signal coupling — no tab sets signals that another tab reads.

More agent context in golid-ai/golid

44 other files this repository gives its agents.