Agent Skills: SOLID TanStack Start

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.168.58 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. Source-file size ceiling

Source files must not exceed FUSE_SOLID_MAX_LINES - the hook's ceiling is the only authority. Split by responsibility when cohesion drops; see references/single-responsibility.md.

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 | |----------|-------| | route.md | createFileRoute component + loader | | server-fn.md | createServerFn with Zod validator | | interface.md | TypeScript interfaces in src/interfaces/ | | hook.md | Client hook wrapping a server function |

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/).
• Source files exceeding FUSE_SOLID_MAX_LINES, missing JSDoc on exports, any type.
• Barrel exports (index.ts re-exports).
• Coding without checking current docs (Context7 + Exa) first.