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/file-organization.md
View on GitHub# File Organization
Proper file and directory structure for maintainable, scalable frontend code.
---
## features/ vs components/ Distinction
### features/ Directory
**Purpose**: Domain-specific features with their own logic, API, and components
**When to use:**
- Feature has multiple related components
- Feature has its own API endpoints
- Feature has domain-specific logic
- Feature has custom hooks/utilities
**Examples:**
- `features/posts/` - Post management
- `features/auth/` - Authentication flows
- `features/dashboard/` - Dashboard feature
**Structure:**
```
features/
my-feature/
api/
myFeatureApi.ts # API service layer
components/
MyFeatureMain.tsx # Main component
SubComponents/ # Related components
hooks/
useMyFeature.ts # Custom hooks
useSuspenseMyFeature.ts # Suspense hooks
helpers/
myFeatureHelpers.ts # Utility functions
types/
index.ts # TypeScript types
index.ts # Public exports
```
### components/ Directory
**Purpose**: Truly reusable UI components that can be used anywhere
**When to use:**
- Component is generic and reusable
- Component has no domain-specific logic
- Component can be used across multiple features
**Examples:**
- `components/SuspenseLoader/`
- `components/CustomAppBar/`
- `components/ErrorBoundary/`
- `components/LoadingOverlay/`
**Structure:**
```
components/
ComponentName/
ComponentName.tsx # Main component
ComponentName.styles.ts # Styles (if > 100 lines)
index.ts # Export
```
---
## Import Aliases
### Available Aliases
```typescript
// Root imports
import { apiClient } from '@/lib/apiClient';
// Type imports
import type { User } from '~types/user';
// Component imports
import { SuspenseLoader } from '~components/SuspenseLoader';
// Feature imports
import { useAuth } from '~features/auth';
```
### Configuration
```json
// tsconfig.json
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"],
"~types/*": ["./src/types/*"],
"~components/*": ["./src/components/*"],
"~features/*": ["./src/features/*"]
}
}
}
```
---
## Naming Conventions
### Files and Directories
| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `UserProfile.tsx` |
| Hooks | camelCase with use prefix | `useAuth.ts` |
| Utils/Helpers | camelCase | `formatDate.ts` |
| Types | camelCase | `user.ts` |
| API Services | camelCase with Api suffix | `userApi.ts` |
| Styles | Same name + .styles | `UserProfile.styles.ts` |
| Tests | Same name + .test | `UserProfile.test.tsx` |
### Directories
| Type | Convention | Example |
|------|------------|---------|
| Features | kebab-case | `user-management/` |
| Components | PascalCase | `UserProfile/` |
| Routes | kebab-case | `project-catalog/` |
---
## Feature Index Exports
### Public API Pattern
```typescript
// features/users/index.ts
// Export only what should be public
// Components
export { UserList } from './components/UserList';
export { UserProfile } from './components/UserProfile';
// Hooks
export { useUsers } from './hooks/useUsers';
// Types
export type { User, CreateUserDTO } from './types';
// API (usually internal, but export if needed)
export { userApi } from './api/userApi';
```
---
## Complete Directory Structure
```
src/
├── features/ # Domain features
│ ├── auth/
│ ├── users/
│ └── posts/
│
├── components/ # Shared components
│ ├── SuspenseLoader/
│ ├── CustomAppBar/
│ ├── ErrorBoundary/
│ └── LoadingOverlay/
│
├── routes/ # TanStack Router routes
│ ├── __root.tsx
│ ├── index.tsx
│ ├── users/
│ │ ├── index.tsx
│ │ └── $userId.tsx
│ └── posts/
│
├── hooks/ # Shared hooks
│ ├── useAuth.ts
│ ├── useMuiSnackbar.ts
│ └── useDebounce.ts
│
├── lib/ # Shared utilities
│ ├── apiClient.ts
│ └── utils.ts
│
├── types/ # Shared TypeScript types
│ ├── user.ts
│ ├── post.ts
│ └── common.ts
│
├── config/ # Configuration
│ └── theme.ts
│
└── App.tsx # Root component
```
---
## Summary
**Key Principles:**
1. **features/** for domain-specific code
2. **components/** for truly reusable UI
3. Use subdirectories: api/, components/, hooks/, helpers/, types/
4. Import aliases for clean imports
5. Consistent naming conventions
6. Export public API from feature index.ts
**See Also:**
- [component-patterns.md](component-patterns.md) - Component structure
- [data-fetching.md](data-fetching.md) - API service patterns
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: 321k | 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 |