File Structure Guidelines

A well-organized file structure is critical for the maintainability and scalability of a frontend application. This document outlines the recommended structure for modern frontend projects.

---

Why a Standardized File Structure Matters

• Scalability: Easily add new features without cluttering the codebase.
• Readability: Make it easier for team members to navigate the project.
• Reusability: Facilitate the reuse of components, utilities, and other resources.
• Maintainability: Simplify debugging and future enhancements.

---

Recommended Folder Structure

Below is an example of a feature-based folder structure for a modern React application:

src/
├── assets/             # Static assets (images, fonts, etc.)
├── components/         # Reusable UI components
├── features/           # Feature-specific code
│   ├── feature1/       # Feature 1
│   │   ├── components/ # Feature-specific components
│   │   ├── hooks/      # Custom hooks for the feature
│   │   ├── pages/      # Pages related to the feature
│   │   ├── services/   # API calls or business logic
│   │   └── types.ts    # TypeScript types for the feature
│   └── feature2/       # Feature 2 (similar structure)
├── hooks/              # Shared custom hooks
├── layouts/            # Layout components (e.g., Sidebar, Header)
├── routes/             # Application routes
├── services/           # Shared services (e.g., API clients)
├── store/              # Global state management (Redux, Zustand, etc.)
├── styles/             # Global styles (CSS, SCSS, or styled-components)
├── types/              # Shared TypeScript types
├── utils/              # Utility functions
├── App.tsx             # Root component
├── index.tsx           # Entry point
└── vite.config.ts      # Vite configuration file

---

Folder Descriptions

src/assets

Contains static assets like images, fonts, and icons.

• Example

  src/assets/
  ├── images/
  │   ├── logo.png
  │   └── banner.jpg
  ├── fonts/
  │   ├── OpenSans-Regular.ttf
  └── icons/
      ├── home.svg
      └── search.svg
  

src/components

Holds reusable UI components that are not tied to any specific feature.

• Example

  src/components/
  ├── Button/
  │   ├── Button.tsx
  │   └── Button.styles.ts
  ├── Modal/
  │   ├── Modal.tsx
  │   └── Modal.styles.ts
  

src/features

Contains feature-specific code grouped by feature. Each feature has its own subdirectory.

• Example:

  src/features/feature1/
  ├── components/
  ├── hooks/
  ├── pages/
  ├── services/
  └── types.ts
  

src/hooks

Shared custom hooks used across multiple features.

• Example:

  src/hooks/
  ├── useAuth.ts
  ├── useFetch.ts
  └── useToggle.ts
  

src/layouts

Defines layout components for the application, such as headers, sidebars, and footers.

• Example:

  src/layouts/
  ├── MainLayout.tsx
  └── AuthLayout.tsx
  

src/routes

Manages the routing logic for the application.

• Example:

  src/routes/
  ├── AppRoutes.tsx
  └── ProtectedRoute.tsx
  

src/services

Contains shared services like API clients or utility libraries for HTTP requests.

• Example:

  src/services/
  ├── apiClient.ts
  └── authService.ts
  

src/store

Manages global state, typically with Redux or another state management library.

• Example:

  src/store/
  ├── slices/
  │   ├── userSlice.ts
  │   └── settingsSlice.ts
  └── store.ts
  

src/styles

Includes global styles, theme definitions, and CSS/SCSS files.

• Example:

  src/styles/
  ├── globals.css
  └── theme.ts
  

src/utils

Utility functions used throughout the application.

• Example:

  src/utils/
  ├── dateFormatter.ts
  ├── debounce.ts
  └── validation.ts
  

---

Best Practices

• Keep It Modular: Group related code together.
• Name Consistently: Use clear, descriptive names for folders and files.
• Avoid Deep Nesting: Keep the folder structure as flat as possible.
• Use Index Files: Export components or utilities from index.ts files for cleaner imports.
• Document Conventions: Include README.md files in larger directories to explain their purpose.

---

Example Usage

Importing a Component

Instead of:

import Button from "../../components/Button/Button";

Use:

import Button from "@/components/Button";

Organizing Feature-Specific Components

Feature-specific components should reside within the respective feature folder to maintain modularity.

---

A well-organized file structure is the foundation of a scalable and maintainable frontend project. Following these guidelines will help you build a robust codebase for your team.