react-components
Use when writing, refactoring, or reviewing React components inside a TanStack Start application. Focuses on SOLID component design, composition, and correct use of loaders, server functions, and React Query for client-side state.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-04
- Stars
- ★ 41
- Forks
- 0
01 前言 Front Matter
- name
- react-components
- description
- Use when writing, refactoring, or reviewing React components inside a TanStack Start application. Focuses on SOLID component design, composition, and correct use of loaders, server functions, and React Query for client-side state.
03 SKILL.md 正文
React Components
When to use this skill
Use this skill ONLY when:
- Writing React components inside an app
- Refactoring React UI code
- Reviewing React components
- Building UI features using TanStack Start
Do NOT use for:
- Backend architecture design
- API design
- Build tooling or infra
- Non-UI server logic
Core Rules
- Components must follow SOLID principles
- Components must stay small and focused
- Data fetching must follow TanStack Start patterns (loaders + server functions) for the web app, or
@repo/api-clientauto-generated hooks for the extension app - Never use
useEffectfor data fetching - Business logic must be extracted into hooks
- Composition is preferred over configuration
- Components must be easy to read and test
- Always use Shadcn UI primitives for UI consistency and accessibility
Data Fetching Architecture (IMPORTANT)
TanStack Start uses a hybrid data model, combined with @repo/api-client:
1. Route Loaders (Server-first, initial data)
Use loaders for:
- Initial page data
- SEO-critical content
- Data required before render
- Avoiding loading states on first paint
Route loaders call either server functions (preferred) or @repo/api-client directly:
// routes/guides/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { getAllGuides } from "@/server-fns/guides";
// OR: import { api } from "@repo/api-client";
export const Route = createFileRoute("/guides/")({
loader: async () => {
// ✅ DO — Call server function (preferred)
const guides = await getAllGuides();
// OR call api-client directly for simple cases:
// const guides = await api.guides.getAllGuides();
return { guides };
},
component: GuidesPage,
});
Consuming loader data
function GuidesPage() {
const { guides } = Route.useLoaderData();
return (
<div>
{guides.map(guide => (
<GuideCard key={guide.id} guide={guide} />
))}
</div>
);
}
2. Server Functions (TanStack Start createServerFn)
Server functions wrap @repo/api-client calls and are the primary data access pattern:
// server-fns/guides.ts
import { createServerFn } from "@tanstack/react-start";
import { api } from "@repo/api-client";
export const getAllGuides = createServerFn({ method: "GET" })
.handler(async () => {
const { data, status } = await api.guides.getAllGuides();
if (status !== 200) {
throw new Error("Failed to fetch guides");
}
return data.guides;
});
export const createGuide = createServerFn({ method: "POST" })
.inputValidator((input: { title: string; description?: string }) => input)
.handler(async ({ data }) => {
const response = await api.guides.createGuide({
title: data.title,
description: data.description ?? null,
});
if (response.status !== 201 || !response.data?.guide) {
return null;
}
return response.data.guide;
});
Server functions:
- Run on the server (not exposed to the client bundle)
- Accept typed inputs via
.inputValidator() - Return typed data (types come from
@repo/api-client) - Are called from route loaders or from client components
3. Client-side Mutations (Web App)
For mutations triggered by user actions, call server functions directly in event handlers:
function CreateGuideForm() {
const navigate = Route.useNavigate();
const handleSubmit = async (data: { title: string; description?: string }) => {
try {
const guide = await createGuide({ data });
if (guide) {
navigate({ to: `/guides/${guide.id}` });
showToastSuccess("Guide created");
}
} catch (error: any) {
showToastError("Error", error.message ?? "Failed to create guide");
}
};
return <Form onSubmit={handleSubmit} />;
}
For TanStack Query-based mutations (with cache invalidation), use useMutation:
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { createGuide } from "@/server-fns/guides";
function useCreateGuideMutation() {
const queryClient = useQueryClient();
const navigate = Route.useNavigate();
return useMutation({
mutationFn: (data: { title: string; description?: string }) =>
createGuide({ data }),
onSuccess: (guide) => {
queryClient.invalidateQueries({ queryKey: ["guides"] });
navigate({ to: `/guides/${guide.id}` });
},
});
}
4. Extension App: @repo/api-client Directly
The extension app uses @repo/api-client directly. Use api.* for programmatic calls (background scripts, services) and auto-generated hooks for React components:
// ✅ DO — Programmatic calls (background scripts, etc.)
import { api } from "@repo/api-client";
async function archiveGuide(guideId: string) {
const response = await api.guides.archiveGuide(guideId);
if (response.status !== 200 || !response.data?.guide) {
return null;
}
return response.data.guide;
}
// ✅ DO — Auto-generated hooks for React components
import { useGetAllGuides, useCreateGuide } from "@repo/api-client";
function GuideList() {
const { data, isLoading, error } = useGetAllGuides();
const createMutation = useCreateGuide({
mutation: {
onSuccess: () => {
showToastSuccess("Guide created");
},
},
});
if (isLoading) return <Spinner />;
if (error) return <ErrorDisplay error={error} />;
return (
<div>
{data?.guides?.map(guide => (
<GuideCard key={guide.id} guide={guide} />
))}
<button onClick={() => createMutation.mutate({ data: { title: "New" } })}>
Create Guide
</button>
</div>
);
}
Data Flow Diagram
Web App (TanStack Start):
Route Loader → Server Function (createServerFn) → api-client (api.guides.*) → API Server
Component UI → Route.useLoaderData() ← typed data
Extension App (WXT / SPA):
Background/Script → api.* from @repo/api-client → API Server
Component → use*() Hook from @repo/api-client → API Server
Generic Component
Use a simple, flat structure for generic components:
// Generic Component
type Props = {
title: string;
description: string;
disabled?: boolean;
onClick: () => void;
};
function ActionButton({ title, description, disabled, onClick }: Props) {
return (
<button disabled={disabled} onClick={onClick}>
<span>{title}</span>
<p>{description}</p>
</button>
);
}
Generic Hook
Always co-locate hooks with the feature they serve:
// hooks/use-guide-mutations.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { api } from "@repo/api-client";
export function usePublishGuide() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (guideId: string) => api.guides.publishGuide(guideId),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ["guides"] });
showToastSuccess("Guide published");
},
onError: (error: any) => {
showToastError("Error", error.message);
},
});
}
Using TanStack Start Forms
Forms use TanStack Form with Zod:
import { useForm } from "@tanstack/react-form";
import { z } from "zod";
const formSchema = z.object({
title: z.string().min(1, "Title is required"),
description: z.string().optional(),
});
function CreateGuideForm() {
const form = useForm({
validators: { onChange: formSchema },
defaultValues: { title: "", description: "" },
onSubmit: async ({ value }) => {
try {
await createGuide({ data: value });
form.reset();
} catch (error: any) {
showToastError("Error", error.message);
}
},
});
return (
<form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
{/* fields */}
</form>
);
}
Rules Summary
✅ DO
- Use route loaders for initial data (web app)
- Use
createServerFnto wrap@repo/api-clientcalls (web app) - Use
@repo/api-clientdirectly (api.*and hooks) for the extension app - Import types from
@repo/api-client - Use
try/catchwith toast for error handling - Use TanStack Form with Zod for form validation
- Use Shadcn UI primitives
- Co-locate hooks with features
❌ DON'T
- Don't use
useEffectfor data fetching - Don't import from
@repo/api-clientdirectly in web app client components — use server functions - Don't create manual
http-{domain}.service.tsfiles for endpoints covered by api-client - Don't bypass route loaders for initial data
- Don't manually type what
z.inferor@repo/api-clienttypes already provide - Don't put API calls directly in components
04 同仓库更多 Skills
typst
Typst document creation and package development. Use when: (1) Working with .typ files, (2) User mentions typst, typst.toml, or typst-cli, (3) Creating or using Typst packages, (4) Developing document templates, (5) Converting Markdown/LaTeX to Typst
shadcn
Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
handoff
Compact the current conversation into a handoff document for another agent to pick up.
grilling
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
grill-me
A relentless interview to sharpen a plan or design.
dont-waffle
Use this skill when answering questions, explaining concepts, writing technical responses, reviewing code, or helping with development tasks. Communicate in clear, simple, standard English. Keep answers concise and focused, remove unnecessary filler and repetition, explain technical ideas in plain language, and structure information so it is easy to read and understand. When showing code, present it clearly with enough context for the developer to understand what it does and where it belongs.