Skip to main content

Project Structure

This document describes the recommended directory structure for the src of a React frontend application.

Description​

The standard frontend project structure is defined as follows.

src/
├── assets/
├── components/
│   ├── AccountSettingsPage/
│   ├── AddressFields/
│   │   ├── index.tsx
│   │   ├── index.test.tsx
│   │   └── styles.ts
│   ├── Avatar.tsx
│   └── Badge/
│       ├── Badge.stories.tsx
|       ├── index.tsx
|       ├── index.test.tsx
|       ├── README.md
|       ├── styles.ts
|       └── test.cypress.tsx
├── contexts/
├── hooks/
├── pages/
├── services/
└── utils/
  • assets - static assets such as images and svg files.
  • components - react components. Depending on the complexity of your components these can either be flat (single file per component) or within subdirectories (single directory per component). Having a subdirectory setup is preferred to keep tests and styles together within the same subdirectory.
  • contexts - react contexts (that implement useContext),
  • hooks - react hooks (functions prefixed with use),
  • pages - application pages.
  • services - integrations with downstream, backend applications and 3rd party APIs.
  • utils - misc utility functions.

This best practice only concerns the src directory. For configurations and integration test directories see the best practice for repo structure.

Rationale​

Splitting files by type helps developer understand where things are and where to find them. Similarly having a deep directory structure would also be counter productive for developers to find files. As a result the standard aims to group similar files together without becoming too deep.

Additionally, by keeping the folder structure as flat as possible and always using absolute imports as opposed to relative imports the benefits are:

  1. Files can always be found by name, without having to know the folder structure.
  2. Files don't have to move around to expose reusable code to other components.
  3. Imports don't break when components are moved around.

Examples​

References & Further Reading​