tanstack-router
TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search/path params, or integrating loaders with TanStack Query.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- tanstack-router
- description
- TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search/path params, or integrating loaders with TanStack Query.
- user-invocable
- false
02 资源文件 1
- 参考文档REFERENCE.md23.4 KB
03 SKILL.md 正文
TanStack Router
Quick start
This repo uses file-based routing with @tanstack/router-plugin/vite and autoCodeSplitting: true. Routes live in src/routes/. The generated route tree (src/routeTree.gen.ts) is never edited manually.
Creating a new page
- Create
src/routes/_authenticated/<page-name>/index.tsx - Use
createFileRoute— the plugin infers the path - Add navigation link in sidebar constants if needed
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/_authenticated/my-page/')({
component: MyPageModule,
});
function MyPageModule() {
return <div>My Page</div>;
}
Workflows
Adding an authenticated route
- [ ] Create route file under
src/routes/_authenticated/ - [ ] Add
beforeLoadwith an inlineability.cannot(action, subject)check if the route is restricted - [ ] Read that action/subject pair against this route — a pair naming the wrong resource still compiles
- [ ] Add loader if data is needed before render
- [ ] Add sidebar navigation entry in
SidebarNavigation/constants.ts - [ ] Run
pnpm run dev:viteto regenerate route tree
Adding search params to a route
- [ ] Define Zod schema with
.catch()fallbacks (not.default()) - [ ] Attach via
validateSearch - [ ] Use
loaderDepsif loader needs search params - [ ] Access in component via
Route.useSearch() - [ ] See REFERENCE.md § Search Params
Adding route with data loading (TanStack Query)
- [ ] Define query options in
src/services/<domain>/queries.ts - [ ] Blocking data:
queryClient.query({ ...factory(), staleTime: 'static' })in loader (queryClient.infiniteQueryfor infinite factories) - [ ] Non-blocking data:
queryClient.query(factory()).catch(noop)—query()rejects on error - [ ] Never
ensureQueryData/fetchQuery/prefetchQuery/*InfiniteQuery*— deprecated, removed in v6 - [ ] Consume with
useSuspenseQuery(blocking) oruseQuery(non-blocking) - [ ] See REFERENCE.md § TanStack Query Integration
Key conventions
| Pattern | This repo's approach |
|---|---|
| Auth guard | _authenticated/route.tsx — beforeLoad checks getAuthToken() + queryClient.query({ ...meQueryOptions(), staleTime: 'static' }), redirects to /login |
| Public routes | _public/route.tsx — beforeLoad optionally resolves auth (no redirect, works for both logged-in and anonymous users) |
| Permission check | No guard helper — beforeLoad({ context: { ability } }) does if (ability.cannot(PERM_ACTIONS.READ, PERM_SUBJECTS.MERCHANT)) throw notFound() |
| Layouts | Pathless _ prefix dirs (_authenticated/, _unauthenticated/, _public/) with <Outlet /> |
| Code splitting | Automatic via Vite plugin — no manual lazy imports needed for routes |
| Search params | Zod validation with .catch(), accessed via Route.useSearch() or getRouteApi() |
| Navigation | <Link> with activeProps for styling; useNavigate() for programmatic nav |
| Router context | queryClient + auth (discriminated union AuthContext) + ability (CASL AppAbility, deny-all until a layout route rebuilds it) passed via createRootRouteWithContext |
| Router config | src/lib/@router.tsx — Wrap (no router hooks) and InnerWrap (router hooks available) for providers |
| Perms provider | Mounted by the layout routes that build an ability (_authenticated, _public), not by a layout component, each passing its own route id as a typed from; _unauthenticated mounts none, so usePerms() is unavailable under it |
| Preloading | defaultPreload: 'intent' — prefetches on hover/focus |
| Error/404 | Global defaults set on router; per-route overrides as needed |
Advanced features
See REFERENCE.md for detailed patterns:
- Route guards, the router-context ability & per-route permission checks
- Search params with Zod validation
- TanStack Query integration (blocking, non-blocking, mixed)
- Navigation patterns (Link, useNavigate, getRouteApi)
- Not-found handling
- Code splitting details
- Router configuration options
04 同仓库更多 Skills
web-security
Enforce web security and avoid security vulnerabilities.
typescript
Write clean, efficient TypeScript code that follows project conventions and advanced type patterns. Use when writing or reviewing TypeScript code, defining types, creating generics, handling errors, or working with React components, Zod schemas, and TanStack libraries.
tanstack-query
TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.
tanstack-form
Build forms using TanStack Form with the project's useAppForm composition, composable field components, Zod validation schemas, FormFieldWrapper error tracking, and form.AppField vs form.Field patterns. Use when creating new forms, adding form fields, writing form validation, or working with TanStack Form in this project.
react
Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.
generate-a-commit-message
Inspects staged/unstaged changes and produces a short, clean Conventional Commit message that satisfies this repo's commitlint.config.js. Delegates phrasing to the `caveman` skill (full) so the subject is terse and free of filler. Auto-detects ticket IDs (e.g. APP-1234) from the current branch and appends a `Refs:` footer. Validates the final message with `pnpm exec commitlint --edit` before presenting. Use when user says "generate commit message", "write commit", "commit msg", "what should the commit be", or invokes /generate-a-commit-message — typically just before `git commit`.