VidyFoo/antigravity-skill-engine / .agent/skills/1-dev/fullstack-guide
fullstack-guide
Verified全栈开发规范百科全书 (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/loading-and-error-states.md
View on GitHub# Loading & Error States
**CRITICAL**: Proper loading and error state handling prevents layout shift and provides better user experience.
---
## ⚠️ CRITICAL RULE: Never Use Early Returns
### The Problem
```typescript
// ❌ NEVER DO THIS - Early return with loading spinner
const Component = () => {
const { data, isLoading } = useQuery();
// WRONG: This causes layout shift and poor UX
if (isLoading) {
return <LoadingSpinner />;
}
return <Content data={data} />;
};
```
**Why this is bad:**
1. **Layout Shift**: Content position jumps when loading completes
2. **CLS (Cumulative Layout Shift)**: Poor Core Web Vital score
3. **Jarring UX**: Page structure changes suddenly
4. **Lost Scroll Position**: User loses place on page
### The Solutions
**Option 1: SuspenseLoader (PREFERRED for new components)**
```typescript
import { SuspenseLoader } from '~components/SuspenseLoader';
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
export const MyComponent: React.FC = () => {
return (
<SuspenseLoader>
<HeavyComponent />
</SuspenseLoader>
);
};
```
**Option 2: LoadingOverlay (for existing components)**
```typescript
import { LoadingOverlay } from '~components/LoadingOverlay';
export const MyComponent: React.FC = () => {
const { data, isLoading } = useQuery({ ... });
return (
<Box sx={{ position: 'relative' }}>
{isLoading && <LoadingOverlay />}
<Content data={data} />
</Box>
);
};
```
---
## SuspenseLoader Component
### 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
}) => {
const defaultFallback = (
<Box sx={{
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
minHeight: 200,
p: 4
}}>
<CircularProgress />
</Box>
);
return (
<Suspense fallback={fallback || defaultFallback}>
{children}
</Suspense>
);
};
```
---
## Error Handling
### useMuiSnackbar Hook
**ALWAYS use `useMuiSnackbar` for user feedback:**
```typescript
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
export const MyComponent: React.FC = () => {
const { showSnackbar } = useMuiSnackbar();
const handleAction = async () => {
try {
await doSomething();
showSnackbar('Success!', 'success');
} catch (error) {
showSnackbar('Something went wrong', 'error');
}
};
};
```
**NEVER use react-toastify** - always use MUI snackbars for consistency.
### Mutation Error Handling
```typescript
const mutation = useMutation({
mutationFn: userApi.create,
onSuccess: () => {
showSnackbar('User created!', 'success');
},
onError: (error) => {
showSnackbar(error.message || 'Failed to create user', 'error');
},
});
```
---
## Error Boundaries
### Component-Level Errors
```typescript
import { ErrorBoundary } from '~components/ErrorBoundary';
export const MyFeature: React.FC = () => {
return (
<ErrorBoundary fallback={<ErrorMessage />}>
<RiskyComponent />
</ErrorBoundary>
);
};
```
### ErrorBoundary Implementation
```typescript
interface Props {
children: React.ReactNode;
fallback?: React.ReactNode;
}
interface State {
hasError: boolean;
error?: Error;
}
export class ErrorBoundary extends React.Component<Props, State> {
state: State = { hasError: false };
static getDerivedStateFromError(error: Error): State {
return { hasError: true, error };
}
componentDidCatch(error: Error, info: React.ErrorInfo) {
console.error('ErrorBoundary caught:', error, info);
}
render() {
if (this.state.hasError) {
return this.props.fallback || <DefaultError />;
}
return this.props.children;
}
}
```
---
## Skeleton Loading
### MUI Skeleton Component
```typescript
import { Skeleton, Box } from '@mui/material';
export const MyComponent: React.FC = () => {
const { data, isLoading } = useQuery({ ... });
return (
<Box sx={{ p: 2 }}>
{isLoading ? (
<>
<Skeleton variant="text" width={200} height={40} />
<Skeleton variant="rectangular" width="100%" height={200} />
<Skeleton variant="text" width="100%" />
</>
) : (
<>
<Typography variant="h5">{data.title}</Typography>
<img src={data.image} />
<Typography>{data.description}</Typography>
</>
)}
</Box>
);
};
```
**Key**: Skeleton must have **same layout** as actual content (no shift)
---
## Summary
**Loading States:**
- ✅ **PREFERRED**: SuspenseLoader + useSuspenseQuery
- ✅ **ACCEPTABLE**: LoadingOverlay
- ✅ **OK**: Skeleton with same layout
- ❌ **NEVER**: Early returns or conditional layout
**Error Handling:**
- ✅ **ALWAYS**: useMuiSnackbar for user feedback
- ❌ **NEVER**: react-toastify
- ✅ Use onError callbacks in queries/mutations
- ✅ Error boundaries for component-level errors
**See Also:**
- [component-patterns.md](component-patterns.md) - Suspense integration
- [data-fetching.md](data-fetching.md) - useSuspenseQuery details
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: 319k | Updated | Claude CodeCodex | Verified | 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: 197k | 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: 197k | 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: 197k | Updated | Claude CodeCodex | Verified | Install |