tanstack-start-architecture
/tanstack-start-architecture
Porządkuje pliki pełnostackowej aplikacji TanStack Start: trasy, funkcje serwerowe, zapytania, mutacje i SSR.
- Autor
- htmujahid ↗
- Repozytorium
- project-structure-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 02.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 5
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Porządkuje pliki pełnostackowej aplikacji TanStack Start: trasy, funkcje serwerowe, zapytania, mutacje i SSR.
Oryginalny opis (EN)
Use when creating, moving, or naming files in a full-stack TanStack Start app (file-based routes, server functions) that also uses TanStack Query, Form, Table, DB, and Devtools, organized by technical layer. Covers routes, server/ (functions, middleware, services, db), lib/queries, lib/mutations, lib/collections, SSR prefetching, server route exceptions, tests, and growth. For frontend-only, use tanstack-router-architecture.
Jak działa
- Target version
- Follow the repo first
- Default directory layout
- Naming conventions
- Dependency direction
- Server routes: exceptions only
- Where things live
- Tests
- Structure at three sizes
- Anti-patterns
Podgląd SKILL.md
---
name: tanstack-start-architecture
description: Use when creating, moving, or naming files in a full-stack TanStack Start app (file-based routes, server functions) that also uses TanStack Query, Form, Table, DB, and Devtools, organized by technical layer. Covers routes, server/ (functions, middleware, services, db), lib/queries, lib/mutations, lib/collections, SSR prefetching, server route exceptions, tests, and growth. For frontend-only, use tanstack-router-architecture.
license: MIT
---
# TanStack Start architecture
Full-stack React app with TanStack Start (TanStack Router plus server functions), grouped by technical role. Same client layers as `tanstack-router-architecture`, plus a top-level `server/` folder. Data code lives in `lib/queries`, `lib/mutations`, and `lib/collections`, and calls server functions. For a frontend-only app, use `tanstack-router-architecture`.
## Target version
Written for TanStack Start (`@tanstack/react-start`, Vite-based), Router v1, Query v5, Form, Table, DB, and Devtools on 2026-10-30. Start's API still changes between releases, so check the installed version for the router entry file and server route syntax.
## Follow the repo first
Read `src/` before creating files. If the project already has conventions (folder names, casing, aliases), use them. Check `vite.config.ts` for the Start plugin and `tsconfig.json` for aliases.
## Default directory layout
```
src/
router.tsx # createRouter, query client, SSR-query integration
routeTree.gen.ts # generated. Commit it. Never edit it.
start.ts # global middleware and start config
routes/ # file-based routes, thin
__root.tsx # document shell, providers, devtools
index.tsx
invoices/
route.tsx
index.tsx
$invoiceId.tsx
-components/ # route-private UI (the - prefix is ignored by the router)
api/ # server routes: exceptions only (see below)
components/
ui/ forms/ tables/ providers/
hooks/
lib/ # client-safe code
queries/ # query keys and queryOptions, call server functions
mutations/ # mutationOptions and useMutation hooks
collections/ # TanStack DB collections
forms/ schemas/ auth/ utils/
server/ # server-only code
functions/ # createServerFn handlers
middleware/ # auth, logging, validation middleware
services/ # business logic
db/ # ORM client, schema, migrations
config/ # client env and constants
types/ styles/ test/
```
Read [references/full-tree.md](references/full-tree.md) when you need the expanded tree. Read [references/data-layer.md](references/data-layer.md) when writing server functions, queries, mutations, collections, loaders, forms, or tables.
- Add a folder on first use. Do not create empty ones.
- Keep a component in the route's `-components/` until a second route uses it.
- Route files do routing only: path, search schema, loader, composition.
## Naming conventions
- Files and folders: kebab-case. Route files follow router conventions.
- Components: `InvoiceTable` in `invoice-table.tsx`. Named exports, except route files, which export `Route`.
- Server functions: `invoice.functions.ts`, exporting `listInvoicesFn`, `createInvoiceFn`.
- Middleware: `auth.middleware.ts`. Services: `invoice.service.ts`.
- Queries: `invoice.queries.ts`. Mutations: `invoice.mutations.ts`. Collections: `invoice.collection.ts`.
- Schemas: `invoice.schema.ts`. Types: `invoice.types.ts`. Hooks: `use-thing.ts`.
- Tests: next to the file. Imports: `@/` maps to `src/`.
## Dependency direction
```
routes -> components -> hooks -> lib/{queries,mutations,collections} -> server/functions -> server/services -> server/db
```
- `lib/queries`, `lib/mutations`, `lib/collections` call `server/functions` only. They never import `server/services` or `server/db`.
- `server/functions` validate input with `lib/schemas`, apply `server/middleware`, call `server/services`. No business logic.
- `server/services` and `server/db` are imported only by `server/` files and server routes. Never by components or `lib/`.
- `components` never import `routes`. `lib/utils`, `lib/schemas`, and `types` are shared by both sides and import nothing from the app.
## Server routes: exceptions only
Add `routes/api/<name>.ts` only for: webhooks, an auth library handler, streaming or SSE endpoints, or endpoints for mobile and other platforms. Keep handlers thin and call `server/services`. Everything else is a server function.
## Where things live
- Env: client vars in `config/env.ts` (`import.meta.env`, `VITE_` prefix). Server secrets in `server/env.ts` (`process.env`), validated at startup. Never import `server/env.ts` from client code. List vars in `.env.example`.
- Query client: create per request in `router.tsx`, pass through router context, and connect with the Router SSR-query integration.
- Devtools: mount Router, Query, and DB devtools in `routes/__root.tsx`, dev only.
- Auth: session helpers in `lib/auth/` (client-safe), session reading and guards in `server/middleware/auth.middleware.ts`. Guard routes with `beforeLoad` in a layout route.
- Client state: prefer search params and the query cache.
## Tests
- Put tests next to the file. Put setup and helpers in `test/`.
- Test services and server function handlers without rendering. Test components with a router and query client wrapper.
- Put end-to-end tests in `e2e/` at the repo root.
## Structure at three sizes
Read [references/growth-stages.md](references/growth-stages.md) when deciding whether to restructure.
### Prototype
Use `routes/`, `components/`, `lib/`. Add `server/functions` and `server/db` on first use.
### Mid-size
Use the default layout. Past about 10 files in a layer, group by resource inside it (`server/services/billing/`).
### Large
Keep the layers. Group by feature inside each layer and mirror it in `routes/`. Enforce boundaries with lint rules.
## Anti-patterns
Read [references/anti-patterns.md](references/anti-patterns.md) when reviewing a layout or before moving files.
- Do not import `server/services` or `server/db` from client code.
- Do not put business logic in server functions or routes.
- Do not add a server route where a server function works.
- Do not write query keys inline. Use the key factory.
- Do not fetch in `useEffect`. Use a loader plus `ensureQueryData`.
- Do not trust server function input. Validate it and check auth in middleware.
- Do not put non-route files in `routes/` without a `-` prefix.
- Do not use PascalCase file names.
Pliki w paczce (5)
- SKILL.md 7 KB
- references/anti-patterns.md 3 KB
- references/data-layer.md 4 KB
- references/full-tree.md 3 KB
- references/growth-stages.md 1 KB
Wersje
W bazie nie ma innych skilli o nazwie tanstack-start-architecture.
Migawka bazy z 13.11.2026 · wersja paczki 2e6c9b711455 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100tanstack-router-architecture
Porządkuje pliki i warstwy aplikacji TanStack Router typu SPA, z zapytaniami, formularzami i tabelami, bez backendu. - 95tanstack-start-best-practices
Podpowiada dobre praktyki TanStack Start: funkcje serwerowe, middleware, SSR, uwierzytelnianie i wdrożenie aplikacji fullstack. - 100tanstack
Obsługuje typowane TanStack w React: Query (pobieranie, cache, mutacje), Router (routing plikowy, parametry wyszukiwania, loadery) i Start (SSR, funkcje serwerowe). - 100solid-tanstack-start
Porządkuje kod TanStack Start, dzieli zbyt duże trasy i funkcje serwerowe oraz przegląda architekturę. - 100tanstack-start
Prowadzi przez budowę aplikacji full-stack w React z TanStack Start: typowane server functions, routing plikowy w trybach SSR, SSG i SPA, middleware, walidacja i wdrożenie. - 100start-routing-data
Pomaga ładować dane w trasach TanStack Start: izomorficzne loadery, TanStack Query w loaderze, mutacje i SSR dla pojedynczej trasy.