<core_principles>
Core Principles
1. Minimize useEffect Usage
Think harder before adding useEffect. Most scenarios have better alternatives:
<when_not_to_use_effect>
When NOT to Use useEffect
Data transformation for rendering:
- ❌ Don't: Use Effect to compute derived state
- ✅ Do: Calculate during render at top level
// ❌ Bad: Cascading updates
const [filteredItems, setFilteredItems] = useState<Item[]>([]);
useEffect(() => {
setFilteredItems(items.filter(item => item.active));
}, [items]);
// ✅ Good: Direct computation
const filteredItems = items.filter(item => item.active);Handling user events:
- ❌ Don't: Use Effect to respond to user actions
- ✅ Do: Handle logic in event handlers
// ❌ Bad: Lost interaction context
useEffect(() => {
if (buttonClicked) {
submitForm();
}
}, [buttonClicked]);
// ✅ Good: Explicit intent
const handleSubmit = () => {
submitForm();
};Caching expensive computations:
- ❌ Don't: Store computed results in state via Effects
- ✅ Do: Use useMemo
// ❌ Bad: Manual memoization
const [expensiveResult, setExpensiveResult] = useState<Result | null>(null);
useEffect(() => {
setExpensiveResult(computeExpensiveValue(data));
}, [data]);
// ✅ Good: useMemo
const expensiveResult = useMemo(() => computeExpensiveValue(data), [data]);Resetting state on prop changes:
- ❌ Don't: Use Effect to reset state
- ✅ Do: Use key prop to force remount
// ❌ Bad: Manual synchronization
useEffect(() => {
setLocalState(defaultValue);
}, [userId]);
// ✅ Good: Key-based reset
<Profile key={userId} userId={userId} /></when_not_to_use_effect>
<legitimate_use_cases>
Legitimate useEffect Use Cases
Only use Effects for:
- Synchronizing with external systems (browser APIs, third-party widgets)
- Data fetching with proper cleanup (avoid race conditions)
- Subscriptions (prefer useSyncExternalStore when possible)
Pattern for data fetching (if not using query client):
useEffect(() => {
let ignore = false;
async function fetchData() {
const result = await api.getData();
if (!ignore) {
setData(result);
}
}
fetchData();
return () => { ignore = true; }; // Cleanup to prevent race conditions
}, [dependency]);</legitimate_use_cases> </core_principles>
<component_definition>
2. Component Definition Style
Always use FC type annotation:
import { FC, PropsWithChildren } from 'react';
// For components without children
type ButtonProps {
label: string;
onClick: () => void;
}
const Button: FC<ButtonProps> = ({ label, onClick }) => {
return <button onClick={onClick}>{label}</button>;
};
// For components that accept children
type CardProps {
title: string;
}
const Card: FC<PropsWithChildren<CardProps>> = ({ title, children }) => {
return (
<div>
<h2>{title}</h2>
<div>{children}</div>
</div>
);
};Never use function declaration syntax:
// ❌ Bad: Avoid this style
function MyComponent(props: Props) {
return <div />;
}</component_definition>
<api_requests>
3. API Request Handling
Never use fetch directly in components. Always use the project's query client.
<detection_workflow>
Detection Workflow
- Check project dependencies in package.json:
- @apollo/client → Use Apollo Client hooks - @tanstack/react-query → Use Tanstack Query hooks - swr → Use SWR hooks
- Search for existing usage patterns:
- Look for useQuery, useMutation, useSWR, useApolloClient in codebase - Follow established patterns for consistency
- Apply appropriate client:
<apollo_client> Apollo Client (GraphQL):
import { useQuery, useMutation, gql } from '@apollo/client';
const GET_USER = gql`
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}
`;
const UserProfile: FC<{ userId: string }> = ({ userId }) => {
const { data, loading, error } = useQuery(GET_USER, {
variables: { id: userId },
});
if (loading) return <Spinner />;
if (error) return <ErrorMessage error={error} />;
return <div>{data.user.name}</div>;
};
// Mutations
const UPDATE_USER = gql`
mutation UpdateUser($id: ID!, $name: String!) {
updateUser(id: $id, name: $name) {
id
name
}
}
`;
const EditForm: FC = () => {
const [updateUser, { loading }] = useMutation(UPDATE_USER);
const handleSubmit = async (values: FormValues) => {
await updateUser({ variables: { id: values.id, name: values.name } });
};
return <form onSubmit={handleSubmit}>...</form>;
};</apollo_client>
<tanstack_query> Tanstack Query (REST):
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
const UserProfile: FC<{ userId: string }> = ({ userId }) => {
const { data, isLoading, error } = useQuery({
queryKey: ['user', userId],
queryFn: () => api.getUser(userId),
});
if (isLoading) return <Spinner />;
if (error) return <ErrorMessage error={error} />;
return <div>{data.name}</div>;
};
// Mutations with cache invalidation
const EditForm: FC = () => {
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: (values: FormValues) => api.updateUser(values),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['user'] });
},
});
const handleSubmit = (values: FormValues) => {
mutation.mutate(values);
};
return <form onSubmit={handleSubmit}>...</form>;
};</tanstack_query>
const UserProfile: FC<{userId: string}> = ({userId}) => {const {data, error, isLoading} = useSWR(/api/users/${userId}, fetcher);
if (isLoading) return; if (error) return;
return {data.name};};
// Mutations const EditForm: FC = () => {const {trigger, isMutating} = useSWRMutation('/api/users', updateUser);
const handleSubmit = async (values: FormValues) => {await trigger(values);};
return...;};
</swr>
</detection_workflow>
**Benefits of query clients**:
- Automatic caching and deduplication
- Loading/error state management
- Race condition handling
- Cache invalidation and refetching
- Optimistic updates support
</api_requests>
</core_principles>
<workflow>
## Implementation Workflow
1. **Before writing component**:
- Identify data dependencies and state requirements
- Think harder: Can state be derived instead of stored?
- Plan event handlers before considering Effects
2. **During implementation**:
- Define component with FC type annotation
- Calculate derived values at top level
- Use useMemo only for expensive computations
- Handle user interactions in event handlers
- Use query client hooks for API requests
3. **Effect review checklist**:
- [ ] Is this synchronizing with an external system?
- [ ] Could this be a calculated value instead?
- [ ] Should this be in an event handler?
- [ ] Am I using the right hook (useMemo, key prop)?
- [ ] If data fetching, is query client available?
4. **If Effect is necessary**:
- Document why Effect is required
- Implement proper cleanup to prevent memory leaks
- Handle race conditions for async operations
</workflow>
<anti_patterns>
## Anti-Patterns to Avoid
❌ **Chaining Effects**:// Bad: Effects triggering each other useEffect(() => setB(a), [a]); useEffect(() => setC(b), [b]);
// Good: Direct computation or single event handler const b = computeB(a); const c = computeC(b);
❌ **Effect-based initialization**:
// Bad: One-time initialization in Effect useEffect(() => { setData(expensiveInit()); }, []);
// Good: useState with initializer const [data] = useState(() => expensiveInit());
❌ **Direct fetch calls**:
// Bad: Manual fetch in component useEffect(() => { fetch('/api/data').then(res => res.json()).then(setData); }, []);
// Good: Use query client const { data } = useQuery({ queryKey: ['data'], queryFn: fetchData });
</anti_patterns>