fusengine/solid-tanstack-start

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.