hamster-react
Hamster-specific React and Next.js patterns. Use when creating pages, components, forms, server actions, or data fetching in apps/web. Complements the react-best-practices skill.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- hamster-react
- version
- 1.1.0
- description
- Hamster-specific React and Next.js patterns. Use when creating pages, components, forms, server actions, or data fetching in apps/web. Complements the react-best-practices skill.
02 资源文件 8
- 参考文档references/rules/cross-browser-events.md3.3 KB
- 参考文档references/rules/data-fetching.md4.5 KB
- 参考文档references/rules/forms.md6.1 KB
- 参考文档references/rules/page-creation.md4.6 KB
- 参考文档references/rules/react-patterns.md5.0 KB
- 参考文档references/rules/server-actions.md3.8 KB
- 参考文档references/rules/translations.md3.6 KB
- 参考文档references/rules/ui-components.md4.9 KB
03 SKILL.md 正文
Hamster React Patterns
Overview
React and Next.js conventions specific to the Hamster Studio monorepo. Covers page creation, server actions, data fetching, forms, and UI components. For general React performance patterns, see the react-best-practices skill.
When to Apply
- Creating new pages or layouts in apps/web
- Writing server actions or route handlers
- Building forms with validation
- Fetching data in server or client components
- Using @kit/ui components
Quick Reference
| Task | Pattern | Reference |
|---|---|---|
| Create page | withI18n, generateMetadata, PageBody |
references/rules/page-creation.md |
| Server action | enhanceAction with schema, 'use server' |
references/rules/server-actions.md |
| Fetch data | Server: direct Supabase, Client: React Query | references/rules/data-fetching.md |
| Build form | react-hook-form + Zod + server action | references/rules/forms.md |
| UI components | Import from @kit/ui/* |
references/rules/ui-components.md |
Architecture Overview
app/home/
├── (user)/ # Personal account context
│ ├── _components/ # Route-specific components
│ ├── _lib/server/ # Loaders, actions
│ └── page.tsx
└── [account]/ # Team account context (slug, not UUID)
├── _components/
├── _lib/server/
└── page.tsx
Key Patterns
Page Structure
import { PageBody } from '@kit/ui/page';
import { Trans } from '@kit/ui/trans';
import { withI18n } from '~/lib/i18n/with-i18n';
export const generateMetadata = async () => {
const i18n = await createI18nServerInstance();
return { title: i18n.t('feature:pageTitle') };
};
function FeaturePage() {
return (
<>
<FeatureHeader title={<Trans i18nKey="common:routes.feature" />} />
<PageBody>{/* Content */}</PageBody>
</>
);
}
export default withI18n(FeaturePage);
Server Action Pattern
'use server';
import { enhanceAction } from '@kit/next/actions';
import { CreateItemSchema } from '../schema/create-item.schema';
export const createItemAction = enhanceAction(
async (data, user) => {
// data validated, user authenticated
const client = getSupabaseServerClient();
const { data: item } = await client.from('items').insert(data).select().single();
return { success: true, item };
},
{ auth: true, schema: CreateItemSchema }
);
Data Fetching Decision
| Context | Use | Example |
|---|---|---|
| Server Component | Direct Supabase | await client.from('items').select() |
| Client Component | React Query + useSupabase |
useQuery({ queryFn: ... }) |
| Admin bypass | getSupabaseServerAdminClient |
Rare, requires manual auth |
Form Pattern
'use client';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { Form, FormField, FormItem, FormControl, FormMessage } from '@kit/ui/form';
import { toast } from '@kit/ui/sonner';
function MyForm() {
const form = useForm({ resolver: zodResolver(Schema) });
const onSubmit = (data) => {
startTransition(async () => {
await toast.promise(myAction(data), {
loading: t('creating'),
success: t('created'),
error: t('error')
});
});
};
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
{/* FormFields */}
</form>
</Form>
);
}
useEffect Rules (CRITICAL)
MUST follow You Might Not Need an Effect. Before writing any useEffect, ask: "Is this synchronizing with an external system?" If not, you probably don't need it.
When useEffect is WRONG
1. Derived state — compute during render instead
// 🔴 WRONG: redundant state + unnecessary Effect
const [fullName, setFullName] = useState('');
useEffect(() => {
setFullName(firstName + ' ' + lastName);
}, [firstName, lastName]);
// ✅ CORRECT: calculate during render
const fullName = firstName + ' ' + lastName;
// ✅ CORRECT: memoize if expensive
const filtered = useMemo(() => getFilteredTodos(todos, filter), [todos, filter]);
2. State reset on prop change — use key or render-time adjustment
// 🔴 WRONG: resetting state in an Effect
useEffect(() => {
setComment('');
}, [userId]);
// ✅ BEST: use key to reset entire component
<Profile userId={userId} key={userId} />
// ✅ OK: render-time adjustment when only partial reset needed
const [prevItems, setPrevItems] = useState(items);
if (items !== prevItems) {
setPrevItems(items);
setSelection(null);
}
// ✅ BEST: derive instead of resetting
const selection = items.find(item => item.id === selectedId) ?? null;
3. Event-specific logic — put it in the event handler
// 🔴 WRONG: event logic in an Effect
useEffect(() => {
if (product.isInCart) {
showNotification(`Added ${product.name}!`);
}
}, [product]);
// ✅ CORRECT: call from the event handler
function handleBuyClick() {
addToCart(product);
showNotification(`Added ${product.name}!`);
}
4. Notifying parent about state changes — call in the event handler
// 🔴 WRONG: notifying parent via Effect
useEffect(() => {
onChange(isOn);
}, [isOn, onChange]);
// ✅ CORRECT: notify during the event that caused the change
function updateToggle(nextIsOn) {
setIsOn(nextIsOn);
onChange(nextIsOn);
}
5. Passing data to parent — lift the fetch up instead
// 🔴 WRONG: child fetches, passes to parent via Effect
function Child({ onFetched }) {
const data = useSomeAPI();
useEffect(() => {
if (data) onFetched(data);
}, [data, onFetched]);
}
// ✅ CORRECT: parent fetches, passes down
function Parent() {
const data = useSomeAPI();
return <Child data={data} />;
}
6. Effect chains — compute in render, update in event handlers
// 🔴 WRONG: chain of Effects triggering each other
useEffect(() => { if (card?.gold) setGoldCount(c => c + 1); }, [card]);
useEffect(() => { if (goldCount > 3) { setRound(r => r + 1); setGoldCount(0); } }, [goldCount]);
useEffect(() => { if (round > 5) setGameOver(true); }, [round]);
// ✅ CORRECT: derive what you can, update in event handler
const isGameOver = round > 5;
function handlePlaceCard(nextCard) {
setCard(nextCard);
if (nextCard.gold) {
if (goldCount < 3) setGoldCount(goldCount + 1);
else { setGoldCount(0); setRound(round + 1); }
}
}
When useEffect IS correct
| Pattern | Why it's correct |
|---|---|
| Subscriptions with cleanup | Synchronizing with external system (realtime channels, WebSocket, event listeners) |
| Data fetching with cleanup | Synchronizing with network (add ignore flag for race conditions) |
| DOM manipulation via refs | Synchronizing with browser DOM (focus, scroll, ResizeObserver) |
| Analytics on mount | Side effect because component was displayed |
| Ref syncs for stale closures | Keeping refs current for callbacks used in subscriptions |
| External store mutations | Synchronizing React state with Zustand/external stores |
Key principle
"If this logic is caused by a particular interaction, keep it in the event handler. If it's caused by the user seeing the component on the screen, keep it in the Effect."
Lint enforcement
The codebase enforces these patterns via:
react-hooks/set-state-in-effect— flags synchronous setState inside effects (useuseEffectEventwrapper for legitimate cases like hydration detection)react-hooks/refs— flags ref access during render (keep ref syncs inuseEffect, not render body)- Consider a community “you might not need an effect” lint plugin for broader detection of redundant effects
Component Guidelines
Server vs Client Components
| Use Server Components | Use Client Components |
|---|---|
| Data fetching | Interactivity (onClick, onChange) |
| Authenticated queries | Browser APIs |
| Static rendering | React hooks (useState, useEffect) |
| No hooks needed | Real-time listeners |
Workspace Contexts
// Personal account
import { useUserWorkspace } from '@kit/accounts/hooks/use-user-workspace';
const { user, account } = useUserWorkspace();
// Team account
import { useTeamAccountWorkspace } from '@kit/team-accounts/hooks/use-team-account-workspace';
const { account, user, accounts } = useTeamAccountWorkspace();
JSX Patterns
// Class merging
import { cn } from '@kit/ui/utils';
<div className={cn('base', { 'active': isActive }, className)} />
// Conditional rendering
import { If } from '@kit/ui/if';
<If condition={isLoading} fallback={<Content />}>
<Spinner />
</If>
// Translations (no hardcoded strings)
import { Trans } from '@kit/ui/trans';
<Trans i18nKey="feature:message" values={{ name }} />
File Organization
| File | Purpose |
|---|---|
page.tsx |
Route page component |
layout.tsx |
Shared layout |
loading.tsx |
Loading state |
error.tsx |
Error boundary |
_components/ |
Route-specific components |
_lib/server/ |
Loaders, actions, queries |
_lib/schema/ |
Zod validation schemas |
References
references/rules/page-creation.md- Creating pages and layoutsreferences/rules/server-actions.md- Server action patternsreferences/rules/data-fetching.md- Data fetching strategiesreferences/rules/forms.md- Form implementationreferences/rules/ui-components.md- UI component usagereferences/rules/react-patterns.md- React component patternsreferences/rules/translations.md- i18n implementation
04 同仓库更多 Skills
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.