/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

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

/**
 * 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.