# Core Architecture Standards for React

This document outlines the core architectural standards for building React applications. It focuses on fundamental patterns, project structure, and organization principles to ensure maintainability, scalability, and performance. These standards are aligned with the latest version of React and incorporate modern best practices.

## 1. Architectural Patterns

Choosing the right architectural pattern is crucial for the long-term success of a React project. This section describes the preferred architectural patterns and provides guidance on when to use them.

### 1.1. Component-Based Architecture

React is fundamentally component-based. Components are independent, reusable building blocks that manage their own state and render UI.

**Do This:**

* Design UIs as a composition of small, focused, and reusable components.

* Favor composition over inheritance.

* Abstract complex logic into custom hooks.

* Use prop types or TypeScript for type checking.

**Don't Do This:**

* Create monolithic components that handle too many responsibilities.

* Rely heavily on inheritance for code reuse.

* Mix UI rendering logic with complex business logic within a single component.

**Why:**

* **Maintainability:** Smaller components are easier to understand, test, and modify.

* **Reusability:** Components can be reused across different parts of the application, reducing code duplication.

* **Testability:** Focused components are easier to test in isolation.

**Example:**

"""jsx

// Good: A simple, reusable button component

import React from 'react';

import PropTypes from 'prop-types';

const Button = ({ children, onClick, className }) => {

return (

{children}

);

};

Button.propTypes = {

children: PropTypes.node.isRequired,

onClick: PropTypes.func,

className: PropTypes.string,

};

export default Button;

// Bad: A button component with too much logic

import React from 'react';

const BadButton = ({ text, onClick, isLoading }) => {

if (isLoading) {

return Loading...; // Logic within the component

}

return {text};

};

"""

### 1.2. Container/Presentational (Smart/Dumb) Components

This pattern separates components into two categories:

* **Container Components:** Handle data fetching, state management, and logic. They may use hooks or other techniques to fulfill that purpose.

* **Presentational Components:** Focus solely on rendering UI based on props. These are purely functional components that depend only on their inputs.

**Do This:**

* Create container components to fetch data and manage state.

* Pass data and callbacks to presentational components via props.

* Keep presentational components as simple and focused as possible.

* Connect container components to state management libraries like Redux or Zustand, if needed.

**Don't Do This:**

* Mix data fetching or state management logic directly within presentational components.

* Introduce side effects within presentational components.

**Why:**

* **Separation of Concerns:** Clearly separates UI rendering from application logic.

* **Testability:** Presentational components are easier to test as they are purely functional.

* **Reusability:** Presentational components can be reused with different data sources.

**Example:**

"""jsx

// Presentational Component (Stateless)

import React from 'react';

import PropTypes from 'prop-types';

const UserProfile = ({ name, email }) => (

{name}

{email}

);

UserProfile.propTypes = {

name: PropTypes.string.isRequired,

email: PropTypes.string.isRequired,

};

export default UserProfile;

// Container Component (Stateful)

import React, { useState, useEffect } from 'react';

import UserProfile from './UserProfile';

const UserProfileContainer = () => {

const [user, setUser] = useState(null);

const [loading, setLoading] = useState(true);

useEffect(() => {

// Simulate fetching user data

setTimeout(() => {

setUser({ name: 'John Doe', email: 'john.doe@example.com' });

setLoading(false);

}, 1000);

}, []);

if (loading) {

return Loading user profile...;

}

return ;

};

export default UserProfileContainer;

"""

### 1.3. Hooks-Based Architecture

React Hooks allow you to use state and other React features in functional components. This promotes cleaner, more reusable code. The best practice is now to use the "use" hook and React Server Components for data fetching.

**Do This:**

* Use built-in hooks like "useState", "useEffect", "useContext", "useRef", "useMemo", and "useCallback".

* Create custom hooks to extract reusable logic.

* Follow the "Rules of Hooks": only call Hooks at the top level of a function component or custom Hook, and only call Hooks from React function components or custom Hooks.

* Consider React Server Components for data fetching and backend integration.

**Don't Do This:**

* Rely on class components for new development.

* Implement complex logic directly within the component body without extraction.

* Ignore linting rules related to hooks (e.g., "eslint-plugin-react-hooks").

**Why:**

* **Code Reusability:** Custom hooks promote code reuse and reduce duplication.

* **Readability:** Hooks make component logic easier to understand and maintain.

* **Testability:** Hooks can be tested independently.

**Example:**

"""jsx

// Custom Hook for Tracking Window Size

import { useState, useEffect } from 'react';

function useWindowSize() {

const [windowSize, setWindowSize] = useState({

width: window.innerWidth,

height: window.innerHeight,

});

useEffect(() => {

function handleResize() {

setWindowSize({

width: window.innerWidth,

height: window.innerHeight,

});

}

window.addEventListener('resize', handleResize);

handleResize(); // Call handler right away so state gets updated with initial window size

return () => window.removeEventListener('resize', handleResize);

}, []); // Empty array ensures that effect is only run on mount and unmount

return windowSize;

}

export default useWindowSize;

// Usage in a Component

import React from 'react';

import useWindowSize from './useWindowSize';

const MyComponent = () => {

const { width, height } = useWindowSize();

return (

Window Width: {width}px

Window Height: {height}px

);

};

export default MyComponent;

"""

### 1.4. React Server Components (RSCs)

React Server Components (RSCs) allow you to render components on the server, improving performance and SEO.

**Do This:**

* Use RSCs for data fetching and backend integration.

* Use the "use" hook in RSCs for data fetching.

* Understand the limitations of RSCs, such as the inability to use client-side interactivity directly.

**Don't Do This:**

* Use RSCs for components that require client-side state or interactivity unless combined cautiously with client components.

**Why:**

* **Performance:** Rendering components on the server reduces the amount of JavaScript that needs to be downloaded and executed on the client.

* **SEO:** Server-rendered content is easier for search engines to crawl.

**Example:**

"""jsx

// Server Component (app/components/Greeting.js)

import { use } from 'react';

async function getData() {

const res = await fetch('https://jsonplaceholder.typicode.com/todos/1');

// Recommendation: handle errors

if (!res.ok) {

// This will activate the closest "error.js" Error Boundary

throw new Error('Failed to fetch data')

}

return res.json()

}

export default function Greeting() {

const data = use(getData());

return Hello, {data.title};

}

"""

## 2. Project Structure and Organization

A well-defined project structure is essential for maintainability and collaboration. This section outlines a recommended project structure for React applications.

### 2.1. Feature-Based Structure

Organize your project around features rather than technology. Each feature should reside in its own directory.

**Do This:**

* Create a "src" directory as the root of your application code.

* Inside "src", create directories for each feature (e.g., "src/users", "src/products").

* Within each feature directory, organize components, hooks, and styles related to that feature.

* Create a "src/shared" directory for components, hooks, and utilities that are used across multiple features.

* Use "src/app" to implement the app layout, and routing infrastructure using Next.js using the "app/" directory.

**Don't Do This:**

* Organize code by technology (e.g., "src/components", "src/hooks", "src/styles"). This makes it harder to find related code.

* Place all components in a single directory.

**Why:**

* **Improved Discoverability:** Feature-based structure makes it easier to find all code related to a specific feature.

* **Reduced Complexity:** Features are encapsulated within their own directories, reducing overall project complexity.

* **Better Collaboration:** Teams can work on different features without interfering with each other.

* **Easier Removal:** It's easier to remove or refactor a specific feature without impacting other parts of the application.

**Example:**

"""

src/

├── app/

│ ├── layout.tsx

│ └── page.tsx

├── components/

│ ├── UserProfile/

│ │ ├── UserProfile.jsx

│ │ ├── UserProfile.module.css

│ │ └── index.js

│ ├── ProductList/

│ │ ├── ProductList.jsx

│ │ ├── ProductList.module.css

│ │ └── index.js

│ └── shared/

│ ├── Button/

│ │ ├── Button.jsx

│ │ └── Button.module.css

│ └── Input/

│ ├── Input.jsx

│ └── Input.module.css

├── hooks/

│ ├── useAuth.js

│ └── useFetch.js

├── services/

│ └── api.js

└── utils/

└── helpers.js

"""

### 2.2. Naming Conventions

Consistent naming conventions improve code readability and maintainability.

**Do This:**

* Use PascalCase for component names (e.g., "UserProfile", "ProductList").

* Use camelCase for variable names (e.g., "userName", "productList").

* Use descriptive and meaningful names.

* Prefix custom hooks with "use" (e.g., "useWindowSize", "useFetchData").

* Name CSS modules with ".module.css" or ".module.scss" extensions (e.g., "UserProfile.module.css").

* Use SCREAMING_SNAKE_CASE for constants.

**Don't Do This:**

* Use cryptic or abbreviated names.

* Use names that conflict with existing libraries or frameworks.

* Use inconsistent naming styles.

**Why:**

* **Readability:** Consistent naming makes code easier to understand.

* **Maintainability:** Naming conventions help developers quickly identify the purpose of code elements.

* **Collaboration:** Consistent naming reduces ambiguity and facilitates collaboration within the team.

**Example:**

"""javascript

// Component Name: PascalCase

const UserProfile = () => { ... };

// Variable Name: camelCase

const userName = 'John Doe';

// Custom Hook Name: use prefix

const useWindowSize = () => { ... };

// CSS Module Name: .module.css extension

import styles from './UserProfile.module.css';

// Constant Name: SCREAMING_SNAKE_CASE

const API_ENDPOINT = 'https://api.example.com';

"""

### 2.3. Module Resolution

Use absolute imports and aliases to improve code readability and avoid relative path hell.

**Do This:**

* Configure your build tool (e.g., Webpack, Parcel) to support absolute imports.

* Define aliases for commonly used directories (e.g., "@components", "@hooks", "@utils").

* Use absolute imports with aliases in your code.

**Don't Do This:**

* Use deeply nested relative paths (e.g., "../../../../components/Button").

**Why:**

* **Readability:** Absolute imports are easier to read and understand.

* **Maintainability:** Absolute imports are less prone to breaking when files are moved.

* **Refactoring:** Easier to refactor the project without breaking imports.

**Example:**

"""javascript

// Webpack Configuration (example)

module.exports = {

resolve: {

alias: {

'@components': path.resolve(__dirname, 'src/components/'),

'@hooks': path.resolve(__dirname, 'src/hooks/'),

'@utils': path.resolve(__dirname, 'src/utils/'),

};

// Usage in a Component

import Button from '@components/Button';

import useWindowSize from '@hooks/useWindowSize';

import { formatDate } from '@utils/helpers';

"""

## 3. Data Management

Proper data management is crucial for performance and maintainability. This section outlines the preferred approaches for managing data in React applications.

### 3.1. State Management Libraries

Choose the right state management library based on the complexity of your application. For very simple cases, the default React Context API and "useState" and "useReducer" hooks may suffice. For medium-complexity apps, consider "Zustand" due to its simplicity. For applications that require more complex global state management, use Redux Toolkit.

**Do This:**

* Start with React's built-in state management tools ("useState", "useContext", "useReducer").

* Consider Zustand for medium-complexity apps for its simplicity and ease of use. It uses a very simple mental model: a single global store with selectors. You can easily create multiple stores this way, if necessary.

* Use Redux Toolkit for applications with complex state management requirements.

* Use middleware (e.g., Redux Thunk, Redux Saga) for handling asynchronous actions in Redux.

* Use selectors to derive data from the state.

**Don't Do This:**

* Use Redux for simple applications where component-level state is sufficient.

* Mutate state directly in Redux.

* Over-engineer state management.

**Why:**

* **Centralized State:** State management libraries provide a centralized store for managing application state.

* **Predictable State Updates:** Redux enforces a unidirectional data flow, making state updates predictable.

* **Improved Performance:** Selectors and memoization techniques can improve performance by preventing unnecessary re-renders.

**Example (Redux Toolkit):**

"""javascript

// store.js

import { configureStore } from '@reduxjs/toolkit';

import counterReducer from '../features/counter/counterSlice';

export const store = configureStore({

reducer: {

counter: counterReducer,

});

// counterSlice.js

import { createSlice } from '@reduxjs/toolkit';

const counterSlice = createSlice({

name: 'counter',

initialState: {

value: 0,

reducers: {

increment: (state) => {

state.value += 1;

decrement: (state) => {

state.value -= 1;

});

export const { increment, decrement } = counterSlice.actions;

export default counterSlice.reducer;

// Component

import React from 'react';

import { useSelector, useDispatch } from 'react-redux';

import { increment, decrement } from './counterSlice';

const Counter = () => {

const count = useSelector((state) => state.counter.value);

const dispatch = useDispatch();

return (

dispatch(increment())}>Increment

{count}

dispatch(decrement())}>Decrement

);

};

export default Counter;

"""

**Example (Zustand):**

"""javascript

import { create } from 'zustand'

import { devtools, persist } from 'zustand/middleware'

let store = (set) => ({

darkMode: false,

toggleDarkMode: () => set((state) => ({ darkMode: !state.darkMode })),

})

store = devtools(store)

store = persist(store, { name: 'darkMode' })

const useStore = create(store)

export default useStore;

//Example of usage of zustand store

import useStore from './store';

const DarkModeButton = () => {

const darkMode = useStore((state) => state.darkMode);

const toggleDarkMode = useStore((state) => state.toggleDarkMode);

return (

{darkMode ? 'Light Mode' : 'Dark Mode'}

);

};

export default DarkModeButton;

"""

### 3.2. Data Fetching

Use appropriate data fetching techniques based on the type of data and the frequency of updates.

**Do This:**

* Use the browser's "fetch" API with "async/await" syntax for making HTTP requests.

* Consider third-party libraries like Axios or "ky" for additional features (e.g., interceptors, automatic retries).

* Use React Query or SWR for caching, deduplication, and background updates.

* Implement error handling and loading states.

* Consider React Server Components and the "use" hook for server-side data fetching.

**Don't Do This:**

* Fetch data directly in component render methods.

* Ignore error handling.

* Over-fetch data.

**Why:**

* **Improved Performance:** Caching and deduplication reduce the number of network requests.

* **Better User Experience:** Loading states and error handling provide feedback to the user.

* **Simplified Code:** Libraries like React Query and SWR simplify data fetching logic.

**Example (React Query):**

"""jsx

import { useQuery } from '@tanstack/react-query';

const fetchTodos = async () => {

const response = await fetch('https://jsonplaceholder.typicode.com/todos');

if (!response.ok) {

throw new Error('Failed to fetch todos');

}

return response.json();

};

const Todos = () => {

const { data, isLoading, isError, error } = useQuery('todos', fetchTodos);

if (isLoading) {

return Loading todos...;

}

if (isError) {

return Error: {error.message};

}

return (

{data.map((todo) => (

{todo.title}

))}

);

};

export default Todos;

"""

## 4. Styling

Consistent and maintainable styling is essential for a good user experience.

### 4.1. CSS-in-JS

Use CSS-in-JS libraries like styled-components or Emotion for modular and maintainable styling.

**Do This:**

* Use styled-components or Emotion to define component-specific styles.

* Use theming to manage global styles and branding.

* Use "css" prop with Emotion for dynamic styles/one-off customizations.

**Don't Do This:**

* Write inline styles directly in JSX (except for very simple cases).

* Use global CSS classes that can conflict with other components.

**Why:**

* **Component-Scoped Styles:** CSS-in-JS styles are scoped to individual components, preventing naming collisions.

* **Dynamic Styles:** CSS-in-JS allows you to easily apply dynamic styles based on props or state.

* **Improved DX:** Streamlined styling workflow with JavaScript integration.

**Example (styled-components):**

"""jsx

import styled from 'styled-components';

const Button = styled.button"

background-color: #007bff;

color: white;

padding: 10px 20px;

border: none;

border-radius: 5px;

cursor: pointer;

&:hover {

background-color: #0056b3;

}

const PrimaryButton = styled(Button)"

font-weight: bold;

const MyComponent = () => {

return Click Me;

};

export default MyComponent;

"""

## 5. Testing

Automated testing is crucial for ensuring the quality of your code. Use frameworks like Jest and React Testing Library for unit and integration tests.

### 5.1. Testing Strategy

Write unit tests, integration tests, and end-to-end tests to cover different aspects of your application.

**Do This:**

* Use Jest as the test runner.

* Use React Testing Library for rendering components and simulating user interactions.

* Write unit tests for individual components, hooks, and utilities.

* Write integration tests to verify interactions between components.

* Use tools like Cypress or Playwright for end-to-end tests.

* Aim for high test coverage.

* Encourage TDD (Test Driven Development).

**Don't Do This:**

* Skip writing tests.

* Write tests that are too tightly coupled to implementation details.

* Rely solely on manual testing.

**Why:**

* **Improved Code Quality:** Testing helps catch bugs early in the development process.

* **Increased Confidence:** Testing provides confidence when making changes or refactoring code.

* **Reduced Risk:** Testing reduces the risk of introducing regressions.

**Example (React Testing Library):**

"""jsx

import React from 'react';

import { render, screen, fireEvent } from '@testing-library/react';

import Button from './Button';

test('renders button with correct text', () => {

render(Click Me);

const buttonElement = screen.getByText(/Click Me/i);

expect(buttonElement).toBeInTheDocument();

});

test('calls onClick handler when button is clicked', () => {

const onClick = jest.fn();

render(Click Me);

const buttonElement = screen.getByText(/Click Me/i);

fireEvent.click(buttonElement);

expect(onClick).toHaveBeenCalledTimes(1);

});

"""

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Core Architecture Standards for React

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Deployment and DevOps Standards for React

Security Best Practices Standards for React

Testing Methodologies Standards for React

State Management Standards for React

Component Design Standards for React