Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

tanstack-start-architecture

/tanstack-start-architecture

Porządkuje pliki pełnostackowej aplikacji TanStack Start: trasy, funkcje serwerowe, zapytania, mutacje i SSR.

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 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

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

Uwagi i zgłoszenia

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