Shell
COMPONENTS.md
Code Patterns That Work
Patterns extracted from real projects. Copy, adapt, ship.
React Patterns
Async State Hook
Handle loading/error/data states cleanly.
type AsyncState<T> =
| { status: 'idle' }
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'error'; error: Error };
function useAsync<T>(asyncFn: () => Promise<T>, deps: any[] = []) {
const [state, setState] = useState<AsyncState<T>>({ status: 'idle' });
useEffect(() => {
setState({ status: 'loading' });
asyncFn()
.then(data => setState({ status: 'success', data }))
.catch(error => setState({ status: 'error', error }));
}, deps);
return state;
}
// Usage
const state = useAsync(() => fetchProjects(), []);
if (state.status === 'loading') return <Spinner />;
if (state.status === 'error') return <Error error={state.error} />;
if (state.status === 'success') return <List data={state.data} />;
Debounced Input
Prevent excessive API calls on user input.
function useDebouncedValue<T>(value: T, delay: number): T {
const [debouncedValue, setDebouncedValue] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebouncedValue(value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debouncedValue;
}
// Usage
function Search() {
const [query, setQuery] = useState('');
const debouncedQuery = useDebouncedValue(query, 300);
useEffect(() => {
if (debouncedQuery) {
searchAPI(debouncedQuery);
}
}, [debouncedQuery]);
return <input value={query} onChange={e => setQuery(e.target.value)} />;
}
Optimistic Updates
Update UI immediately, reconcile with server.
function useOptimisticUpdate<T>(
initialData: T,
updateFn: (data: T) => Promise<T>
) {
const [data, setData] = useState(initialData);
const [pending, setPending] = useState(false);
const update = async (optimisticData: T) => {
const previousData = data;
setData(optimisticData); // Optimistic
setPending(true);
try {
const serverData = await updateFn(optimisticData);
setData(serverData); // Reconcile
} catch (error) {
setData(previousData); // Rollback
throw error;
} finally {
setPending(false);
}
};
return { data, update, pending };
}
Local Storage Sync
Persist state to localStorage with SSR safety.
function useLocalStorage<T>(key: string, initialValue: T) {
const [storedValue, setStoredValue] = useState<T>(() => {
if (typeof window === 'undefined') return initialValue;
try {
const item = window.localStorage.getItem(key);
return item ? JSON.parse(item) : initialValue;
} catch {
return initialValue;
}
});
const setValue = (value: T | ((val: T) => T)) => {
const valueToStore = value instanceof Function ? value(storedValue) : value;
setStoredValue(valueToStore);
if (typeof window !== 'undefined') {
window.localStorage.setItem(key, JSON.stringify(valueToStore));
}
};
return [storedValue, setValue] as const;
}
API Patterns
Fetch Wrapper with Error Handling
class APIError extends Error {
constructor(
message: string,
public status: number,
public data?: any
) {
super(message);
this.name = 'APIError';
}
}
async function api<T>(
endpoint: string,
options: RequestInit = {}
): Promise<T> {
const response = await fetch(`${BASE_URL}${endpoint}`, {
...options,
headers: {
'Content-Type': 'application/json',
...options.headers,
},
});
if (!response.ok) {
const data = await response.json().catch(() => null);
throw new APIError(
data?.message || 'Request failed',
response.status,
data
);
}
return response.json();
}
// Usage
const projects = await api<Project[]>('/projects');
const created = await api<Project>('/projects', {
method: 'POST',
body: JSON.stringify({ name: 'New Project' }),
});
Retry with Exponential Backoff
async function withRetry<T>(
fn: () => Promise<T>,
options: { maxRetries?: number; baseDelay?: number } = {}
): Promise<T> {
const { maxRetries = 3, baseDelay = 1000 } = options;
let lastError: Error;
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
lastError = error as Error;
if (attempt < maxRetries - 1) {
const delay = baseDelay * Math.pow(2, attempt);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
throw lastError!;
}
// Usage
const data = await withRetry(() => api('/flaky-endpoint'), {
maxRetries: 3,
baseDelay: 500,
});
Rate Limiter
function createRateLimiter(maxRequests: number, windowMs: number) {
const requests: number[] = [];
return async function limit<T>(fn: () => Promise<T>): Promise<T> {
const now = Date.now();
// Remove old requests outside window
while (requests.length && requests[0] < now - windowMs) {
requests.shift();
}
if (requests.length >= maxRequests) {
const waitTime = requests[0] + windowMs - now;
await new Promise(resolve => setTimeout(resolve, waitTime));
return limit(fn);
}
requests.push(now);
return fn();
};
}
// Usage
const limiter = createRateLimiter(10, 1000); // 10 requests per second
const result = await limiter(() => api('/endpoint'));
Data Patterns
ID Generator
// Simple unique ID (good for client-side)
function createId(): string {
return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
}
// Prefixed ID (good for type identification)
function createPrefixedId(prefix: string): string {
return `${prefix}_${createId()}`;
}
// Usage
const projectId = createPrefixedId('proj'); // "proj_lx1234_abc1234"
const versionId = createPrefixedId('ver'); // "ver_lx1235_def5678"
Deep Clone / Merge
function deepClone<T>(obj: T): T {
return JSON.parse(JSON.stringify(obj));
}
function deepMerge<T extends object>(target: T, source: Partial<T>): T {
const result = { ...target };
for (const key in source) {
const sourceValue = source[key];
const targetValue = result[key];
if (
sourceValue &&
typeof sourceValue === 'object' &&
!Array.isArray(sourceValue) &&
targetValue &&
typeof targetValue === 'object'
) {
result[key] = deepMerge(targetValue, sourceValue as any);
} else if (sourceValue !== undefined) {
result[key] = sourceValue as any;
}
}
return result;
}
Safe JSON Parse
function safeJsonParse<T>(
json: string,
fallback: T
): T {
try {
return JSON.parse(json) as T;
} catch {
return fallback;
}
}
// With validation
function parseAndValidate<T>(
json: string,
validator: (data: unknown) => data is T,
fallback: T
): T {
try {
const parsed = JSON.parse(json);
return validator(parsed) ? parsed : fallback;
} catch {
return fallback;
}
}
UI Patterns
Keyboard Shortcut Hook
function useKeyboardShortcut(
key: string,
callback: () => void,
modifiers: { ctrl?: boolean; meta?: boolean; shift?: boolean } = {}
) {
useEffect(() => {
const handler = (event: KeyboardEvent) => {
const { ctrl, meta, shift } = modifiers;
if (
event.key.toLowerCase() === key.toLowerCase() &&
(!ctrl || event.ctrlKey) &&
(!meta || event.metaKey) &&
(!shift || event.shiftKey)
) {
event.preventDefault();
callback();
}
};
window.addEventListener('keydown', handler);
return () => window.removeEventListener('keydown', handler);
}, [key, callback, modifiers]);
}
// Usage
useKeyboardShortcut('s', handleSave, { meta: true }); // Cmd+S
useKeyboardShortcut('k', openSearch, { meta: true }); // Cmd+K
Click Outside Hook
function useClickOutside(
ref: RefObject<HTMLElement>,
callback: () => void
) {
useEffect(() => {
const handler = (event: MouseEvent) => {
if (ref.current && !ref.current.contains(event.target as Node)) {
callback();
}
};
document.addEventListener('mousedown', handler);
return () => document.removeEventListener('mousedown', handler);
}, [ref, callback]);
}
// Usage
function Dropdown() {
const [open, setOpen] = useState(false);
const ref = useRef<HTMLDivElement>(null);
useClickOutside(ref, () => setOpen(false));
return (
<div ref={ref}>
<button onClick={() => setOpen(!open)}>Toggle</button>
{open && <div>Dropdown content</div>}
</div>
);
}
Adding New Patterns
When you extract a reusable pattern:
### [Pattern Name]
[Brief description of what it does]
\`\`\`typescript
// Code here
\`\`\`
// Usage example
**Good for**: [Use cases]
**Extracted from**: [Project]
Remember
Don't abstract too early. Extract patterns after you've used them 2-3 times.