VidyFoo/antigravity-skill-engine / .agent/skills/1-dev/fullstack-guide
fullstack-guide
Unverified全栈开发规范百科全书 (React/TS/Node/Supabase). Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend/backend code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| resources/common-patterns.md | markdown | 4.8 KB |
| resources/component-patterns.md | markdown | 4.5 KB |
| resources/data-fetching.md | markdown | 5.4 KB |
| resources/file-organization.md | markdown | 4.9 KB |
| resources/loading-and-error-states.md | markdown | 5.5 KB |
| resources/resources/architecture-overview.md | markdown | 7.8 KB |
| resources/resources/async-and-errors.md | markdown | 6.1 KB |
| resources/resources/testing-guide.md | markdown | 6.9 KB |
| resources/resources/validation-patterns.md | markdown | 7.8 KB |
| resources/routing-guide.md | markdown | 4.7 KB |
| resources/styling-guide.md | markdown | 4.6 KB |
| resources/typescript-standards.md | markdown | 5.4 KB |
resources/component-patterns.md
View on GitHub# Component Patterns
Modern React component architecture emphasizing type safety, lazy loading, and Suspense boundaries.
---
## React.FC Pattern (PREFERRED)
### Why React.FC
All components use the `React.FC<Props>` pattern for:
- Explicit type safety for props
- Consistent component signatures
- Clear prop interface documentation
- Better IDE autocomplete
### Basic Pattern
```typescript
import React from 'react';
interface MyComponentProps {
/** User ID to display */
userId: number;
/** Optional callback when action occurs */
onAction?: () => void;
}
export const MyComponent: React.FC<MyComponentProps> = ({ userId, onAction }) => {
return (
<div>
User: {userId}
</div>
);
};
export default MyComponent;
```
**Key Points:**
- Props interface defined separately with JSDoc comments
- `React.FC<Props>` provides type safety
- Destructure props in parameters
- Default export at bottom
---
## Lazy Loading Pattern
### When to Lazy Load
Lazy load components that are:
- Heavy (DataGrid, charts, rich text editors)
- Route-level components
- Conditionally rendered (modals, dialogs)
### Implementation
```typescript
import React, { lazy } from 'react';
import { SuspenseLoader } from '~components/SuspenseLoader';
// Lazy load the component
const HeavyDataGrid = lazy(() => import('./HeavyDataGrid'));
export const MyFeature: React.FC = () => {
return (
<SuspenseLoader>
<HeavyDataGrid />
</SuspenseLoader>
);
};
```
### Named Export Handling
```typescript
// If component uses named export
const MyComponent = lazy(() =>
import('./MyComponent').then((module) => ({ default: module.MyComponent }))
);
```
---
## SuspenseLoader Component
### Usage
```typescript
import { SuspenseLoader } from '~components/SuspenseLoader';
// Basic usage
<SuspenseLoader>
<MyComponent />
</SuspenseLoader>
// With custom fallback
<SuspenseLoader fallback={<CustomSkeleton />}>
<MyComponent />
</SuspenseLoader>
```
### Implementation
```typescript
import React, { Suspense } from 'react';
import { Box, CircularProgress } from '@mui/material';
interface SuspenseLoaderProps {
children: React.ReactNode;
fallback?: React.ReactNode;
}
export const SuspenseLoader: React.FC<SuspenseLoaderProps> = ({
children,
fallback = <DefaultLoader />
}) => {
return (
<Suspense fallback={fallback}>
{children}
</Suspense>
);
};
const DefaultLoader: React.FC = () => (
<Box sx={{ display: 'flex', justifyContent: 'center', p: 4 }}>
<CircularProgress />
</Box>
);
```
---
## Data Fetching in Components
### useSuspenseQuery Pattern
```typescript
import { useSuspenseQuery } from '@tanstack/react-query';
export const MyComponent: React.FC<Props> = ({ id }) => {
// No isLoading - Suspense handles it!
const { data } = useSuspenseQuery({
queryKey: ['entity', id],
queryFn: () => api.getEntity(id),
});
// data is ALWAYS defined here
return <div>{data.name}</div>;
};
```
---
## Event Handlers
### useCallback Pattern
```typescript
import { useCallback } from 'react';
export const MyComponent: React.FC<Props> = ({ onSave }) => {
const handleClick = useCallback(() => {
// Logic
onSave?.();
}, [onSave]);
const handleChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
setValue(event.target.value);
}, []);
return <Button onClick={handleClick}>Save</Button>;
};
```
---
## Advanced Patterns
### Compound Components
```typescript
// Card.tsx
export const Card: React.FC<CardProps> & {
Header: typeof CardHeader;
Body: typeof CardBody;
Footer: typeof CardFooter;
} = ({ children }) => {
return <Paper>{children}</Paper>;
};
Card.Header = CardHeader;
Card.Body = CardBody;
Card.Footer = CardFooter;
// Usage
<Card>
<Card.Header>Title</Card.Header>
<Card.Body>Content</Card.Body>
<Card.Footer>Actions</Card.Footer>
</Card>
```
---
## Summary
**Modern Component Recipe:**
1. `React.FC<Props>` with TypeScript
2. Lazy load if heavy: `React.lazy(() => import())`
3. Wrap in `<SuspenseLoader>` for loading
4. Use `useSuspenseQuery` for data
5. Import aliases (@/, ~types, ~components)
6. Event handlers with `useCallback`
7. Default export at bottom
8. No early returns for loading states
**See Also:**
- [data-fetching.md](data-fetching.md) - useSuspenseQuery details
- [loading-and-error-states.md](loading-and-error-states.md) - Suspense best practices
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |