davila7/claude-code-templates / cli-tool/components/skills/development/frontend-dev-guidelines
frontend-dev-guidelines
VerifiedFrontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, MUI v7 styling, TanStack Router, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
| resources/common-patterns.md | markdown | 8.2 KB |
| resources/complete-examples.md | markdown | 23.9 KB |
| resources/component-patterns.md | markdown | 10.6 KB |
| resources/data-fetching.md | markdown | 19.4 KB |
| resources/file-organization.md | markdown | 11.6 KB |
| resources/loading-and-error-states.md | markdown | 11.8 KB |
| resources/performance.md | markdown | 9.4 KB |
| resources/routing-guide.md | markdown | 7.0 KB |
| resources/styling-guide.md | markdown | 7.7 KB |
| resources/typescript-standards.md | markdown | 8.2 KB |
resources/file-organization.md
View on GitHub# File Organization
Proper file and directory structure for maintainable, scalable frontend code in the the application.
---
## 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/` - Project catalog/post management
- `features/blogs/` - Blog builder and rendering
- `features/auth/` - Authentication flows
**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 components used across multiple features
**When to use:**
- Component is used in 3+ places
- Component is generic (no feature-specific logic)
- Component is a UI primitive or pattern
**Examples:**
- `components/SuspenseLoader/` - Loading wrapper
- `components/CustomAppBar/` - Application header
- `components/ErrorBoundary/` - Error handling
- `components/LoadingOverlay/` - Loading overlay
**Structure:**
```
components/
SuspenseLoader/
SuspenseLoader.tsx
SuspenseLoader.test.tsx
CustomAppBar/
CustomAppBar.tsx
CustomAppBar.test.tsx
```
---
## Feature Directory Structure (Detailed)
### Complete Feature Example
Based on `features/posts/` structure:
```
features/
posts/
api/
postApi.ts # API service layer (GET, POST, PUT, DELETE)
components/
PostTable.tsx # Main container component
grids/
PostDataGrid/
PostDataGrid.tsx
drawers/
ProjectPostDrawer/
ProjectPostDrawer.tsx
cells/
editors/
TextEditCell.tsx
renderers/
DateCell.tsx
toolbar/
CustomToolbar.tsx
hooks/
usePostQueries.ts # Regular queries
useSuspensePost.ts # Suspense queries
usePostMutations.ts # Mutations
useGridLayout.ts # Feature-specific hooks
helpers/
postHelpers.ts # Utility functions
validation.ts # Validation logic
types/
index.ts # TypeScript types/interfaces
queries/
postQueries.ts # Query key factories (optional)
context/
PostContext.tsx # React context (if needed)
index.ts # Public API exports
```
### Subdirectory Guidelines
#### api/ Directory
**Purpose**: Centralized API calls for the feature
**Files:**
- `{feature}Api.ts` - Main API service
**Pattern:**
```typescript
// features/my-feature/api/myFeatureApi.ts
import apiClient from '@/lib/apiClient';
export const myFeatureApi = {
getItem: async (id: number) => {
const { data } = await apiClient.get(`/blog/items/${id}`);
return data;
},
createItem: async (payload) => {
const { data } = await apiClient.post('/blog/items', payload);
return data;
},
};
```
#### components/ Directory
**Purpose**: Feature-specific components
**Organization:**
- Flat structure if <5 components
- Subdirectories by responsibility if >5 components
**Examples:**
```
components/
MyFeatureMain.tsx # Main component
MyFeatureHeader.tsx # Supporting components
MyFeatureFooter.tsx
# OR with subdirectories:
containers/
MyFeatureContainer.tsx
presentational/
MyFeatureDisplay.tsx
blogs/
MyFeatureBlog.tsx
```
#### hooks/ Directory
**Purpose**: Custom hooks for the feature
**Naming:**
- `use` prefix (camelCase)
- Descriptive of what they do
**Examples:**
```
hooks/
useMyFeature.ts # Main hook
useSuspenseMyFeature.ts # Suspense version
useMyFeatureMutations.ts # Mutations
useMyFeatureFilters.ts # Filters/search
```
#### helpers/ Directory
**Purpose**: Utility functions specific to the feature
**Examples:**
```
helpers/
myFeatureHelpers.ts # General utilities
validation.ts # Validation logic
transblogers.ts # Data transblogations
constants.ts # Constants
```
#### types/ Directory
**Purpose**: TypeScript types and interfaces
**Files:**
```
types/
index.ts # Main types, exported
internal.ts # Internal types (not exported)
```
---
## Import Aliases (Vite Configuration)
### Available Aliases
From `vite.config.ts` lines 180-185:
| Alias | Resolves To | Use For |
|-------|-------------|---------|
| `@/` | `src/` | Absolute imports from src root |
| `~types` | `src/types` | Shared TypeScript types |
| `~components` | `src/components` | Reusable components |
| `~features` | `src/features` | Feature imports |
### Usage Examples
```typescript
// ✅ PREFERRED - Use aliases for absolute imports
import { apiClient } from '@/lib/apiClient';
import { SuspenseLoader } from '~components/SuspenseLoader';
import { postApi } from '~features/posts/api/postApi';
import type { User } from '~types/user';
// ❌ AVOID - Relative paths from deep nesting
import { apiClient } from '../../../lib/apiClient';
import { SuspenseLoader } from '../../../components/SuspenseLoader';
```
### When to Use Which Alias
**@/ (General)**:
- Lib utilities: `@/lib/apiClient`
- Hooks: `@/hooks/useAuth`
- Config: `@/config/theme`
- Shared services: `@/services/authService`
**~types (Type Imports)**:
```typescript
import type { Post } from '~types/post';
import type { User, UserRole } from '~types/user';
```
**~components (Reusable Components)**:
```typescript
import { SuspenseLoader } from '~components/SuspenseLoader';
import { CustomAppBar } from '~components/CustomAppBar';
import { ErrorBoundary } from '~components/ErrorBoundary';
```
**~features (Feature Imports)**:
```typescript
import { postApi } from '~features/posts/api/postApi';
import { useAuth } from '~features/auth/hooks/useAuth';
```
---
## File Naming Conventions
### Components
**Pattern**: PascalCase with `.tsx` extension
```
MyComponent.tsx
PostDataGrid.tsx
CustomAppBar.tsx
```
**Avoid:**
- camelCase: `myComponent.tsx` ❌
- kebab-case: `my-component.tsx` ❌
- All caps: `MYCOMPONENT.tsx` ❌
### Hooks
**Pattern**: camelCase with `use` prefix, `.ts` extension
```
useMyFeature.ts
useSuspensePost.ts
useAuth.ts
useGridLayout.ts
```
### API Services
**Pattern**: camelCase with `Api` suffix, `.ts` extension
```
myFeatureApi.ts
postApi.ts
userApi.ts
```
### Helpers/Utilities
**Pattern**: camelCase with descriptive name, `.ts` extension
```
myFeatureHelpers.ts
validation.ts
transblogers.ts
constants.ts
```
### Types
**Pattern**: camelCase, `index.ts` or descriptive name
```
types/index.ts
types/post.ts
types/user.ts
```
---
## When to Create a New Feature
### Create New Feature When:
- Multiple related components (>3)
- Has own API endpoints
- Domain-specific logic
- Will grow over time
- Reused across multiple routes
**Example:** `features/posts/`
- 20+ components
- Own API service
- Complex state management
- Used in multiple routes
### Add to Existing Feature When:
- Related to existing feature
- Shares same API
- Logically grouped
- Extends existing functionality
**Example:** Adding export dialog to posts feature
### Create Reusable Component When:
- Used across 3+ features
- Generic, no domain logic
- Pure presentation
- Shared pattern
**Example:** `components/SuspenseLoader/`
---
## Import Organization
### Import Order (Recommended)
```typescript
// 1. React and React-related
import React, { useState, useCallback, useMemo } from 'react';
import { lazy } from 'react';
// 2. Third-party libraries (alphabetical)
import { Box, Paper, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
import { createFileRoute } from '@tanstack/react-router';
// 3. Alias imports (@ first, then ~)
import { apiClient } from '@/lib/apiClient';
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
import { SuspenseLoader } from '~components/SuspenseLoader';
import { postApi } from '~features/posts/api/postApi';
// 4. Type imports (grouped)
import type { Post } from '~types/post';
import type { User } from '~types/user';
// 5. Relative imports (same feature)
import { MySubComponent } from './MySubComponent';
import { useMyFeature } from '../hooks/useMyFeature';
import { myFeatureHelpers } from '../helpers/myFeatureHelpers';
```
**Use single quotes** for all imports (project standard)
---
## Public API Pattern
### feature/index.ts
Export public API from feature for clean imports:
```typescript
// features/my-feature/index.ts
// Export main components
export { MyFeatureMain } from './components/MyFeatureMain';
export { MyFeatureHeader } from './components/MyFeatureHeader';
// Export hooks
export { useMyFeature } from './hooks/useMyFeature';
export { useSuspenseMyFeature } from './hooks/useSuspenseMyFeature';
// Export API
export { myFeatureApi } from './api/myFeatureApi';
// Export types
export type { MyFeatureData, MyFeatureConfig } from './types';
```
**Usage:**
```typescript
// ✅ Clean import from feature index
import { MyFeatureMain, useMyFeature } from '~features/my-feature';
// ❌ Avoid deep imports (but OK if needed)
import { MyFeatureMain } from '~features/my-feature/components/MyFeatureMain';
```
---
## Directory Structure Visualization
```
src/
├── features/ # Domain-specific features
│ ├── posts/
│ │ ├── api/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── helpers/
│ │ ├── types/
│ │ └── index.ts
│ ├── blogs/
│ └── auth/
│
├── components/ # Reusable components
│ ├── SuspenseLoader/
│ ├── CustomAppBar/
│ ├── ErrorBoundary/
│ └── LoadingOverlay/
│
├── routes/ # TanStack Router routes
│ ├── __root.tsx
│ ├── index.tsx
│ ├── project-catalog/
│ │ ├── index.tsx
│ │ └── create/
│ └── blogs/
│
├── 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 (@/, ~types, ~components, ~features)
5. Consistent naming: PascalCase components, camelCase utilities
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
- [complete-examples.md](complete-examples.md) - Full feature exampleRelated 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: 322k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |