Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

tanstack-router-architecture

/tanstack-router-architecture

Porządkuje pliki i warstwy aplikacji TanStack Router typu SPA, z zapytaniami, formularzami i tabelami, bez backendu.

Licencja
MIT
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Target version
  2. Follow the repo first
  3. Default directory layout
  4. Naming conventions
  5. Dependency direction
  6. Where things live
  7. Tests
  8. Structure at three sizes
  9. Anti-patterns
Sekcje z nagłówków SKILL.md, w oryginale · 119 linii, 781 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.