Project Structure & Best Practices

A well-organized project structure is essential for React applications to remain maintainable as they grow. This guide covers practical folder organization patterns and naming conventions.

Standard React Project Structure

Basic Structure

Every React project should start with this foundational structure:

Directorysrc/
- Directorycomponents/
  - …
- Directoryhooks/
  - …
- Directorycontexts/
  - …
- Directoryservices/
  - …
- Directorypages/
  - …
- Directoryassets/
  - …
- Directoryutils/
  - …
- App.js
- index.js

Folder Purposes

components/: Reusable UI components
hooks/: Custom React hooks
contexts/: React Context providers
services/: API calls and external service integrations
pages/: Top-level page components (for routing)
assets/: Images, icons, fonts, and static files
utils/: Helper functions and utilities

Structuring Approaches

Layer-Based Structure

Organize by technical layers (recommended for most projects):

Structure
Benefits

Directorysrc/
- Directorycomponents/
  - Directoryui/
    Button.jsx
    Input.jsx
    Modal.jsx
  - Directorylayout/
    Header.jsx
    Sidebar.jsx
    Footer.jsx
  - Directoryforms/
    LoginForm.jsx
    SignupForm.jsx
- Directoryhooks/
  - useAuth.js
  - useLocalStorage.js
- Directoryservices/
  - api.js
  - authService.js
- Directorycontexts/
  - AuthContext.js
  - ThemeContext.js

Feature-Based Structure

Organize by business features (for complex applications):

Structure
Benefits

Directorysrc/
- Directoryfeatures/
  - Directoryauth/
    Directorycomponents/
    DirectoryLoginForm/
    …
    DirectorySignupForm/
    …
    Directoryhooks/
    useAuth.js
    Directoryservices/
    authService.js
    index.js
  - Directorydashboard/
    Directorycomponents/
    DirectoryDashboardCard/
    …
    DirectoryStatsWidget/
    …
    Directoryhooks/
    useDashboard.js
    Directoryservices/
    dashboardService.js
  - Directoryprofile/
    Directorycomponents/
    DirectoryProfileForm/
    …
    DirectoryAvatarUpload/
    …
    Directoryhooks/
    useProfile.js
- Directoryshared/
  - Directorycomponents/
    Button.jsx
    Input.jsx
  - Directoryhooks/
    …
  - Directoryutils/
    …

File Naming Conventions

Component Files

# PascalCase for component files
UserProfile.jsx
NavigationMenu.jsx
ProductCard.jsx

# Include component type in folder structure
components/forms/LoginForm.jsx
components/ui/Button.jsx
components/layout/Header.jsx

Import Aliases Setup

Vite Configuration

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@hooks': path.resolve(__dirname, './src/hooks'),
      '@services': path.resolve(__dirname, './src/services'),
      '@utils': path.resolve(__dirname, './src/utils'),
      '@assets': path.resolve(__dirname, './src/assets'),
      '@pages': path.resolve(__dirname, './src/pages')
    }
  }
});

Usage Examples

// Without aliases
import Button from '../../../components/ui/Button/Button';
import { useAuth } from '../../../hooks/useAuth';
import { userService } from '../../../services/userService';

// With aliases
import Button from '@components/ui/Button';
import { useAuth } from '@hooks/useAuth';
import { userService } from '@services/userService';

When to Refactor Structure

Signs You Need Better Organization

Import Paths Getting Long: ../../../components/ui/Button
Hard to Find Components: Spending time looking for files
Naming Conflicts: Multiple components with similar names
Large Folders: More than 10-15 files in a single folder
Feature Coupling: Changes in one area break unrelated features

Migration Strategy

Start Small: Begin with one feature or component type
Update Imports: Use find/replace for import paths
Setup Aliases: Configure path aliases before big moves
Test Thoroughly: Ensure nothing breaks during restructuring
Document Changes: Update team on new conventions