Cursor TanStack 编码规范

Cursor TanStack 编码规范：来自 PatrickJS/awesome-cursorrules (40k stars) 的 tan，适用于各类文档与内容的智能化处理。

Skill Documentation

Cursor TanStack 编码规范

摘要

Cursor TanStack 编码规范：来自 PatrickJS/awesome-cursorrules (40k stars) 的 tan，适用于各类文档与内容的智能化处理。

**文件来源:** PatrickJS/awesome-cursorrules → `rules/tanstack-router.mdc`

**原仓库:** https://github.com/PatrickJS/awesome-cursorrules

**评分:** ⭐ 仓库 40k stars (社区最权威 Cursor rules 合集)

这个 skill 是干什么的?

把 `tanstack-router.mdc` 这条 Cursor 编码规则打包成可调用的 AI skill,帮你把代码生成统一到一致的标准上。

> Type-safe routing with TanStack Router v1 for React apps, including file-based routing, loaders, search params validation, auth guards, and TanStack Query integration

🤖 Agent 使用说明

• **输入:** 一段要生成/重构的代码需求
• **输出:** 严格遵守 `tanstack-router.mdc` 规则的代码
• **触发:** 用户说"用 X 规范写代码" / "按 tanstack 风格生成" / "用 PatrickJS 的 X 规则"

👤 用户需要做什么?

• [ ] 知道这条规则适合用在什么场景(参考下面"适用场景")
• [ ] 把规则原文内容应用到 IDE 项目的 `.cursor/rules/` 目录(直接复制 .mdc 文件)
• [ ] 调本 skill 时说清楚你的代码任务(语言/框架/目标)
• [ ] 输出后人工 review 风格是否符合预期

适用场景

• 想用统一规范生成 `tanstack` 项目代码
• 团队需要把 AI 代码生成收敛到固定风格
• 学习业界最佳实践的工程化模板

原始规则内容

globs: ["src/routes/**/*", "src/routeTree.gen.ts", "app.config.ts"]
alwaysApply: false
---
You are an expert in TanStack Router v1, React, TypeScript, and type-safe client-side routing.

## Core Principles
- TanStack Router is 100% type-safe — leverage TypeScript generics for params, search params, and loader data
- Prefer file-based routing with `@tanstack/router-vite-plugin` for scalability
- Always define routes with `createFileRoute` or `createRootRoute`
- Route data loading belongs in `loader` functions, not in component `useEffect`
- Search params are first-class — always define their schema with Zod for type safety

## File-Based Route Conventions

src/routes/

__root.tsx ← Root layout

index.tsx ← / route

posts/

index.tsx ← /posts

$postId.tsx ← /posts/:postId (dynamic)

_layout.tsx ← Layout route (no path segment)

_auth/ ← Pathless auth layout group

dashboard.tsx

## Route Definition

export const Route = createFileRoute('/posts/$postId')({

loader: async ({ params }) => fetchPost(params.postId),

component: PostComponent,

errorComponent: ({ error }) => <ErrorBanner message={error.message} />,

pendingComponent: () => <PostSkeleton />,

})

function PostComponent() {

const post = Route.useLoaderData() // type-safe

const { postId } = Route.useParams() // type-safe

return <div>{post.title}</div>

}

## Type-Safe Search Params
- Always define search params with Zod and `validateSearch`
- Access with `Route.useSearch()` — never read `window.location.search` directly

const searchSchema = z.object({

page: z.number().int().min(1).default(1),

q: z.string().optional(),

})

export const Route = createFileRoute('/search')({

validateSearch: searchSchema,

component: SearchPage,

})

## Navigation
- Use `<Link>` for internal navigation — never `<a href>`
- Always pass typed `params` and `search` — the compiler will catch mistakes

<Link to="/posts/$postId" params={{ postId: '123' }}>View Post</Link>

## Loaders + TanStack Query Integration

export const Route = createFileRoute('/posts')({

loader: ({ context: { queryClient } }) =>

queryClient.ensureQueryData(postsQueryOptions()),

component: PostsPage,

})

## Router Context for Dependency Injection

// __root.tsx

interface RouterContext { queryClient: QueryClient; auth: AuthState }

export const Route = createRootRouteWithContext<RouterContext>()({ component: RootLayout })

// main.tsx

const router = createRouter({ routeTree, context: { queryClient, auth } })

## Auth Guards

export const Route = createFileRoute('/_auth/dashboard')({

beforeLoad: ({ context }) => {

if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })

},

component: Dashboard,

})

## Performance
- Set `defaultPreload: 'intent'` on router for automatic prefetching on hover/focus
- Use `React.lazy` for route component code splitting
- Install `@tanstac

...(完整内容在原仓库)...

数据来源

• 仓库: PatrickJS/awesome-cursorrules (40,581 stars, 257 个 .mdc 规则)
• 抓取时间: 2026-08-17
• License: 跟随原仓库(MIT)

联系方式

有问题或建议,在本 skill 下留言。