Solid Tanstack Start

---
name: solid-tanstack-start
version: 1.0.0
description: Use when organizing TanStack Start code, splitting oversized routes/server functions, or reviewing architecture. Do NOT use for setup or plain React SPA.
user-invocable: true
references: references/solid-principles.md, references/single-responsibility.md, references/architecture-patterns.md, references/interface-segregation.md, references/dependency-inversion.md, references/templates/route.md, references/templates/server-fn.md, references/templates/interface.md, references/templates/hook.md
---

<objective>
Applies SOLID principles and clean architecture to TanStack Start v1.166.2 projects: files under 100 lines (with per-type budgets — route components < 50, server functions < 40, hooks < 30), types declared only in src/interfaces/ (never inline in a route or component file), JSDoc on every export, and a modular directory structure built around the Start route tree.

Establishes the isomorphic/server-only boundary as an architectural concern: DB access, secrets, and filesystem work must sit behind createServerFn or createServerOnlyFn, never inside a bare loader.

Absolute rules include never hand-editing the generated src/routeTree.gen.ts, no module importing another feature module except cores/, no barrel exports, and no `any` types. Includes code templates for routes, server functions, interfaces, and hooks, and DRY guidance to grep for existing logic in src/modules/cores/ or src/lib/ before writing new code.

Do NOT use this skill for initial framework setup (use start-core), for the server/client execution-boundary deep dive itself (use start-execution-model), or for a generic React SPA that has no Start route tree (use solid-react).
</objective>

# SOLID TanStack Start

SOLID and clean architecture for **TanStack Start v1.166.2** projects (Vite plugin
`tanstackStart()`, file-based routes in `src/routes/`, server functions via
`createServerFn`). Start code is isomorphic by default — architecture must make
the server/client boundary explicit.

## Codebase Analysis (MANDATORY)

**Before ANY implementation:**
1. Explore the `src/routes/` tree and existing `modules/` to learn conventions.
2. Read related route files and their `createServerFn` wrappers.
3. Identify naming, path aliases (`~/`, `@/`), and data-flow patterns.

## DRY - Reuse or Create Shared (MANDATORY)

**Before writing ANY new code:**
1. **Grep** for similar function names, loaders, or server functions.
2. Check shared locations: `src/modules/cores/`, `src/lib/`.
3. If similar code exists → extend/reuse instead of duplicating.
4. Logic used by 2+ features → put it in `src/modules/cores/` directly.
5. Run `npx jscpd ./src --threshold 3` after creating new files.

---

## Absolute Rules (MANDATORY)

### 1. Files < 100 lines

Split at 90. Per-type limits in `references/single-responsibility.md`
(route components < 50, server functions < 40, hooks < 30).

### 2. NEVER edit `src/routeTree.gen.ts`

It is generated by the `tanstackStart()` plugin on every dev/build run. Editing
it by hand is always wrong — the change is overwritten and route types break.
Add/rename files in `src/routes/` instead and let the plugin regenerate it.

### 3. Interfaces Separated

```text
src/modules/[feature]/src/interfaces/
├── user.interface.ts
└── api.interface.ts
```

**NEVER declare types inside a route or component file.** See
`references/interface-segregation.md`.

### 4. JSDoc Mandatory on every export

```typescript
/**
 * Fetch a user by ID (server-only).
 *
 * @param data - Lookup payload with the user id
 * @returns The user row, or throws notFound()
 */
export const getUser = createServerFn({ method: 'GET' })
  .validator((data: { id: string }) => data)
  .handler(async ({ data }) => findUserById(data.id))
```

### 5. Server-only logic lives behind `createServerFn`

Loaders are isomorphic. DB access, secrets, and filesystem MUST sit inside a
`createServerFn().handler()` (or a `createServerOnlyFn`), never a bare loader.
See `start-execution-model` for the full boundary model.

---

## SOLID Principles (Detailed Guides)

1. **`references/single-responsibility.md`** — Load when a route/server function
   grows past its limit; line budgets + split strategy for Start files.
2. **`references/interface-segregation.md`** — Load when designing route loader
   data, server-function payloads, or router context; keep them focused.
3. **`references/dependency-inversion.md`** — Load when a server function calls a
   service; depend on abstractions in `interfaces/`, inject implementations.

See `references/solid-principles.md` for the overview and
`references/architecture-patterns.md` for the full directory layout.

---

## Code Templates

Ready-to-copy code in `references/templates/`:

| Template | Usage | Max Lines |
|----------|-------|-----------|
| `route.md` | `createFileRoute` component + loader | 50 |
| `server-fn.md` | `createServerFn` with Zod validator | 40 |
| `interface.md` | TypeScript interfaces in `src/interfaces/` | - |
| `hook.md` | Client hook wrapping a server function | 30 |

---

## Forbidden

- Editing `src/routeTree.gen.ts` (generated).
- Types declared inside route/component files.
- DB / secrets / filesystem in a bare loader (→ `createServerFn`).
- Module importing another feature module (except `cores/`).
- Files > 100 lines, missing JSDoc on exports, `any` type.
- Barrel exports (`index.ts` re-exports).
- Coding without checking current docs (Context7 + Exa) first.