266 lines
10 KiB
Markdown
266 lines
10 KiB
Markdown
# Project Development Guidelines
|
|
|
|
**Version**: 1.0
|
|
**Last Updated**: July 1, 2025
|
|
|
|
## 1\. Introduction
|
|
|
|
This document provides the official guidelines for developing this application. Its purpose is to ensure a consistent, maintainable, and high-quality codebase. Adhering to these standards is mandatory for all contributors.
|
|
|
|
---
|
|
|
|
## 2\. Project Structure
|
|
|
|
We use a **feature-based structure** to ensure modularity and scalability.
|
|
|
|
```
|
|
/
|
|
├── src/
|
|
│ ├── assets/
|
|
│ ├── components/ # Only for shared components (e.g., App Layout, Button)
|
|
│ ├── config/
|
|
│ ├── contexts/
|
|
│ ├── features/ # Main directory for all application features
|
|
│ │ ├── authentication/
|
|
│ │ │ ├── api/
|
|
│ │ │ │ └── authAPI.ts
|
|
│ │ │ ├── components/
|
|
│ │ │ │ └── LoginForm.tsx
|
|
│ │ │ ├── hooks/
|
|
│ │ │ │ └── useAuth.ts
|
|
│ │ │ ├── routes/
|
|
│ │ │ │ └── LoginPage.tsx # The main entry point for this feature's route
|
|
│ │ │ └── types.ts
|
|
│ │ │
|
|
│ │ └── products/
|
|
│ │ ├── api/
|
|
│ │ │ └── productsAPI.ts
|
|
│ │ ├── components/
|
|
│ │ │ ├── ProductCard.tsx
|
|
│ │ │ └── ProductGrid.tsx
|
|
│ │ ├── routes/
|
|
│ │ │ └── ProductListPage.tsx
|
|
│ │ └── index.ts
|
|
│ │
|
|
│ ├── hooks/ # Only for global hooks
|
|
│ ├── lib/ # For external library configurations (e.g., axios instance)
|
|
│ ├── providers/ # A single place for all context providers
|
|
│ ├── routes/ # Central route configuration
|
|
│ │ └── index.tsx
|
|
│ ├── types/ # Only for global types
|
|
│ ├── App.tsx
|
|
│ └── main.tsx
|
|
│
|
|
```
|
|
|
|
- **`src/features/`**: All code related to a specific business feature (e.g., `authentication`, `products`, `user-profile`) resides within its own folder here. Each feature folder should contain its own `components`, `hooks`, `api`, `types`, and `routes`.
|
|
- **`src/components/`**: This directory is **only** for truly generic, shared UI components that are used across multiple features (e.g., `Button`, `Layout`, `Logo`).
|
|
- **`src/lib/`**: For configuring and exporting instances of third-party libraries (e.g., an `axios` client).
|
|
- **`src/providers/`**: A single location to compose all React Context providers (`AuthProvider`, `ThemeProvider`, etc.).
|
|
- **`src/routes/`**: The central routing configuration, which lazy-loads page components from the `features` directory.
|
|
- **`src/theme/`**: Contains the MUI theme definition and global styles.
|
|
|
|
---
|
|
|
|
## 3\. Naming Conventions
|
|
|
|
Consistent naming is critical for readability.
|
|
|
|
- **Files**:
|
|
- **Components**: **`PascalCase.tsx`** (e.g., `ProductCard.tsx`)
|
|
- **Hooks**: **`useCamelCase.ts`** (e.g., `useDebounce.ts`)
|
|
- **All other `.ts` files**: **`camelCase.ts`** (e.g., `authService.ts`)
|
|
|
|
- **Components**: **`PascalCase`**. The component function name must match the filename.
|
|
|
|
```tsx
|
|
// src/components/SubmitButton.tsx
|
|
function SubmitButton() {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
- **Variables and Functions**: **`camelCase`**.
|
|
|
|
```typescript
|
|
const userCount = 10;
|
|
function getUserProfile() {
|
|
/* ... */
|
|
}
|
|
```
|
|
|
|
- **Constants**: **`UPPER_SNAKE_CASE`**. For constant values that are hardcoded and reused.
|
|
|
|
```typescript
|
|
const MAX_LOGIN_ATTEMPTS = 5;
|
|
```
|
|
|
|
- **Types and Interfaces**: **`PascalCase`**.
|
|
|
|
```typescript
|
|
interface UserProfile {
|
|
userId: string;
|
|
displayName: string;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4\. Coding Best Practices
|
|
|
|
- **Functional Components**: All components **must** be functional components using React Hooks. Class components are not permitted.
|
|
- **TypeScript**: Use TypeScript's features to your advantage. Avoid `any` whenever possible. Define clear types and interfaces for props, API responses, and complex objects.
|
|
- **Props**: Always define props with a `type` or `interface`. Use destructuring in the component signature for clarity.
|
|
|
|
```tsx
|
|
interface UserCardProps {
|
|
name: string;
|
|
avatarUrl: string;
|
|
}
|
|
|
|
function UserCard({ name, avatarUrl }: UserCardProps) {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
- **Imports**: Use absolute paths with the `@/` alias for cleaner imports.
|
|
- **DRY (Don't Repeat Yourself)**: If you use a piece of logic more than twice, abstract it into a custom hook. If you use a piece of JSX more than twice, create a reusable component.
|
|
|
|
---
|
|
|
|
## 5\. State Management
|
|
|
|
- **Local State**: `useState` and `useReducer` are the default choices for component-level state.
|
|
- **Shared State**: For state that needs to be shared across the application (e.g., user authentication, theme), use the **React Context API**.
|
|
|
|
---
|
|
|
|
## 6\. Styling
|
|
|
|
Styling is handled by **Material-UI (MUI)**.
|
|
|
|
- For creating new, reusable, styled components, use the **`styled()` utility** from MUI.
|
|
- For one-off style adjustments or layout overrides, use the **`sx` prop**.
|
|
|
|
---
|
|
|
|
## 7\. Component Documentation (Storybook)
|
|
|
|
All shared UI components in the `src/components` directory **must** be documented using **Storybook**. This creates a living style guide, allows for isolated component development, and makes it easy for all developers to discover and use existing components.
|
|
|
|
Each component folder should contain a `*.stories.tsx` file.
|
|
|
|
---
|
|
|
|
## 8\. Code Comments
|
|
|
|
- **Comment the _Why_, Not the _What_**: Your code should be self-documenting. Use comments to explain _why_ a complex or non-obvious piece of code exists.
|
|
|
|
```typescript
|
|
// Bad comment
|
|
// Increment the counter
|
|
counter++;
|
|
|
|
// Good comment
|
|
// We need to pre-increment the counter to account for the zero-based index of the array.
|
|
++preemptiveCounter;
|
|
```
|
|
|
|
- **JSDoc**: Use JSDoc blocks for all exported functions and custom hooks to enable better editor IntelliSense.
|
|
```typescript
|
|
/**
|
|
* Fetches a user profile from the API.
|
|
* @param userId - The ID of the user to fetch.
|
|
* @returns The user profile object or null if not found.
|
|
*/
|
|
```
|
|
|
|
---
|
|
|
|
## 9\. Git Workflow
|
|
|
|
We use a simplified GitFlow model.
|
|
|
|
1. **Create a Branch**: All work must be done on a feature branch, named descriptively (e.g., `feat/login-page`, `fix/header-bug`).
|
|
2. **Commit Often**: Make small, logical commits. Commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat:`, `fix:`, `docs:`, `chore:`).
|
|
3. **Create a Pull Request (PR)**: When the feature is complete, create a PR against the `main` branch.
|
|
4. **Code Review**: At least one other team member must review and approve the PR.
|
|
5. **Merge**: Once approved and all checks pass, the PR can be merged.
|
|
|
|
---
|
|
|
|
## 10\. Pre-Commit Checklist
|
|
|
|
Before creating a Pull Request, ensure you have:
|
|
|
|
- ✅ Formatted the entire codebase: `npm run format`
|
|
- ✅ Passed all linter checks: `npm run lint`
|
|
- ✅ Documented any new shared components in Storybook.
|
|
|
|
---
|
|
|
|
## 11\. Design Patterns
|
|
|
|
Design patterns are reusable solutions to common problems within a given context. Here are the key patterns we will use in this React project.
|
|
|
|
### Component Design Patterns
|
|
|
|
- **Container/Presentational Pattern (Smart/Dumb Components)**
|
|
- **Concept**: Separate the "how things work" from the "how things look."
|
|
- **Container (Smart) Component**: Manages state, fetches data, and contains business logic. It doesn't have many styles.
|
|
- **Presentational (Dumb) Component**: Receives data via props and simply renders UI. It contains no business logic.
|
|
- **Example**: A `UserProfilePage` (container) fetches user data and passes it to a `UserProfileCard` (presentational) to display.
|
|
|
|
- **Composition Pattern**
|
|
- **Concept**: Build complex components by combining simpler, more generic ones. This is React's core philosophy.
|
|
- **Example**: Using the `children` prop to create a generic `Card` component that can wrap any content:
|
|
```tsx
|
|
<Card>
|
|
<h2>Title</h2>
|
|
<p>Content</p>
|
|
</Card>
|
|
```
|
|
|
|
### State Management Patterns
|
|
|
|
- **Provider Pattern**
|
|
- **Concept**: Make data available to a deep tree of components without having to pass props down manually at every level.
|
|
- **How we use it**: This is the pattern that powers the React Context API. Our `AuthProvider`, `ThemeProvider`, and `CustomThemeProvider` all use this pattern to provide authentication status and theme information to any component that needs it.
|
|
|
|
### Reusable Logic Patterns
|
|
|
|
- **Custom Hooks**
|
|
- **Concept**: The modern, standard way to share stateful logic between components.
|
|
- **How we use it**: By extracting logic into a function whose name starts with `use` (e.g., `useAuth`, `useTheme`), we can reuse that logic in any component without repeating code. This is the preferred replacement for older patterns like HOCs and Render Props.
|
|
|
|
### Memoization Pattern
|
|
|
|
* **Concept**: A performance optimization technique to prevent unnecessary re-renders and expensive re-calculations by caching results. React provides three main tools for this.
|
|
|
|
* **Best For**: Improving the performance of applications with complex components, large lists, or frequent state updates.
|
|
|
|
* **The Tools**:
|
|
|
|
* **`React.memo`**: A higher-order component that prevents a component from re-rendering if its props haven't changed.
|
|
* **`useMemo`**: A hook that caches the result of an expensive calculation. It only re-computes the value when its dependencies change.
|
|
* **`useCallback`**: A hook that caches a function definition. This is useful for preventing child components from re-rendering when you pass functions down as props.
|
|
|
|
|
|
### Custom Data Fetching Hook
|
|
|
|
* **Concept**: A custom hook that abstracts all the logic for fetching data from an API. It typically manages the loading, error, and data states internally.
|
|
|
|
* **Best For**: Simplifying data fetching in your components, eliminating repetitive `useEffect` logic, and creating a consistent way to handle API requests across your app.
|
|
|
|
* **How it looks**: Components become much cleaner and focused on displaying the data.
|
|
|
|
```tsx
|
|
function UserProfile({ userId }) {
|
|
const { data: user, isLoading, error } = useFetch(`/api/users/${userId}`);
|
|
|
|
if (isLoading) return <div>Loading...</div>;
|
|
if (error) return <div>Error fetching data!</div>;
|
|
|
|
return <div>{user.name}</div>;
|
|
}
|
|
``` |