tanstack-router-architecture
/tanstack-router-architecture
Porządkuje pliki i warstwy aplikacji TanStack Router typu SPA, z zapytaniami, formularzami i tabelami, bez backendu.
- 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 i warstwy aplikacji TanStack Router typu SPA, z zapytaniami, formularzami i tabelami, bez backendu.
Oryginalny opis (EN)
Use when creating, moving, or naming files in a frontend-only TanStack Router app (Vite SPA, file-based routes) that also uses TanStack Query, Form, Table, DB, and Devtools, organized by technical layer. Backend is out of scope. Covers routes, components, lib/queries, lib/mutations, lib/collections, import direction, tests, and growth. For full-stack, use tanstack-start-architecture.
Jak działa
- Target version
- Follow the repo first
- Default directory layout
- Naming conventions
- Dependency direction
- Where things live
- Tests
- Structure at three sizes
- Anti-patterns
Podgląd SKILL.md
---
name: tanstack-router-architecture
description: Use when creating, moving, or naming files in a frontend-only TanStack Router app (Vite SPA, file-based routes) that also uses TanStack Query, Form, Table, DB, and Devtools, organized by technical layer. Backend is out of scope. Covers routes, components, lib/queries, lib/mutations, lib/collections, import direction, tests, and growth. For full-stack, use tanstack-start-architecture.
license: MIT
---
# TanStack Router architecture
Client-only React app with TanStack Router (file-based routes) on Vite, grouped by technical role. Data code lives in `lib/queries`, `lib/mutations`, and `lib/collections`. The backend is a separate service and is out of scope: the app only calls it through `lib/api/`. For a full-stack app, use `tanstack-start-architecture`.
## Target version
Written for TanStack Router v1 (file-based, `@tanstack/router-plugin`), TanStack Query v5, Form, Table, DB, and Devtools on 2026-10-30. TanStack DB moves fast, so check its installed version before copying patterns.
## 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 router plugin options (`routesDirectory`, code splitting) and `tsconfig.json` for aliases.
## Default directory layout
```
src/
main.tsx # mounts <RouterProvider />
router.tsx # createRouter, context ({ queryClient }), defaults
routeTree.gen.ts # generated by the plugin. Commit it. Never edit it.
routes/ # file-based routes, thin
__root.tsx # root layout, providers, devtools
index.tsx
invoices/
route.tsx # layout and loader for /invoices
index.tsx
$invoiceId.tsx
-components/ # route-private UI (the - prefix is ignored by the router)
components/ # shared UI used by 2+ routes
ui/ # primitives (Button, Dialog)
forms/ # TanStack Form field components
tables/ # TanStack Table wrappers and column helpers
providers/ # query provider, theme, devtools
hooks/ # shared UI hooks (useDebounce, useInvoiceTable)
lib/
queries/ # query keys and queryOptions, one file per resource
mutations/ # mutationOptions and useMutation hooks
collections/ # TanStack DB collections and live-query helpers
api/ # HTTP client and request functions for the backend
forms/ # createFormHook setup and shared validators
schemas/ # zod (or similar) schemas for forms and responses
auth/ # session helpers, route guards
utils/ # pure helpers
config/ # env parsing 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 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, then move it to `components/`.
- Route files do routing only: path, loader, search schema, and composing components.
## Naming conventions
- Files and folders: kebab-case. Route files follow router conventions (`$param`, `_pathless`, `route.tsx`, `index.tsx`, `-private`).
- Components: `InvoiceTable` in `invoice-table.tsx`. Named exports, except route files, which export `Route`.
- Queries: `invoice.queries.ts`, exporting `invoiceKeys`, `invoiceListOptions`, `invoiceDetailOptions`.
- Mutations: `invoice.mutations.ts`, exporting `useCreateInvoice`, `useDeleteInvoice`.
- Collections: `invoice.collection.ts`, exporting `invoiceCollection`.
- API: `invoice.api.ts`. Schemas: `invoice.schema.ts`. Types: `invoice.types.ts`. Hooks: `use-thing.ts`.
- Tests: `invoice-table.test.tsx` next to the file.
- Imports: `@/` maps to `src/`. Never use `../../..`.
## Dependency direction
```
routes -> components -> hooks -> lib/{queries,mutations,collections} -> lib/api -> lib/{schemas,utils}
```
- `routes` may import any layer below.
- `components` import `hooks`, `lib`, and other components. Never `routes`.
- `lib/queries`, `lib/mutations`, `lib/collections` call `lib/api` and `lib/schemas`. Never components or hooks.
- `lib/api` imports `config`, `lib/schemas`, `types`. Only it calls the backend.
- `lib/utils` and `types` import nothing from the app.
## Where things live
- Config: `config/env.ts` is the only place that reads `import.meta.env`. Prefix vars with `VITE_`. List them in `.env.example`.
- Query client: create in `router.tsx` and pass through router context. Provider in `components/providers/`.
- Devtools: mount Router, Query, and DB devtools in `routes/__root.tsx` or `components/providers/devtools.tsx`, dev only.
- Global client state: prefer router search params and the query cache. Use a small store only for true UI state.
- Auth guards: `beforeLoad` in a layout route (`_authed/route.tsx`), using `lib/auth/`.
## Tests
- Put tests next to the file. Put setup and helpers in `test/`.
- Test queries, mutations, and utils 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/`, and `lib/`. Add `lib/queries` on first API call.
### Mid-size
Use the default layout. Past about 10 files in a layer, group by resource inside it (`lib/queries/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 call `fetch` or the API client from a component. Use `lib/queries` or `lib/mutations`.
- Do not write query keys inline. Use the key factory.
- Do not put data fetching in `useEffect`. Use a loader plus `ensureQueryData`.
- Do not edit `routeTree.gen.ts`.
- Do not put non-route files in `routes/` without a `-` prefix.
- Do not copy query data into `useState` or a store.
- Do not put backend code in this app.
- Do not use PascalCase file names.
Pliki w paczce (5)
- SKILL.md 6 KB
- references/anti-patterns.md 2 KB
- references/data-layer.md 3 KB
- references/full-tree.md 3 KB
- references/growth-stages.md 1 KB
Wersje
W bazie nie ma innych skilli o nazwie tanstack-router-architecture.
Migawka bazy z 13.11.2026 · wersja paczki 1c5b0decd99b (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-start-architecture
Porządkuje pliki pełnostackowej aplikacji TanStack Start: trasy, funkcje serwerowe, zapytania, mutacje i SSR. - 100tanstack-router
Konfiguruje typowany routing plikowy TanStack Router dla React w aplikacjach SPA, z integracją TanStack Query, Cloudflare Workers i rozwiązywaniem błędów devtools oraz bundlowania Vite. - 100nextjs-layered-architecture
Porządkuje pliki w aplikacji Next.js według warstw technicznych: komponenty, akcje, usługi, zapytania i bazę, dla małych i średnich projektów. - 100react-tanstack-router
Wdraża routing w aplikacji React z TanStack Router: trasy plikowe, loadery i parametry wyszukiwania, poza Next.js. - 100solid-tanstack-start
Porządkuje kod TanStack Start, dzieli zbyt duże trasy i funkcje serwerowe oraz przegląda architekturę. - 100set-up-routing
Dodaje routing po stronie klienta do SPA: TanStack Router lub Vue Router z dzieleniem kodu, loaderami i strażnikami chronionych tras.