Folder Structure of a React Project

Intro

This is a guide for organizing your code when using React and styled-components, which is a CSS-IN-JS library, meaning you write the styling in a javascript file. There are other options for CSS solutions and their trade-offs, but that is topic for a different time.

Throughout the doing my projects, I felt the need of some structure for scaling my development. With a bit of luck and exploration, I stumbled upon the concepts of Directory-per-Component and Directory-per-view. There is a great resource talking about this structure at Survive.js.

Folder structure — How to organize the whole

The basic folder structure should follow something like this:

• src/
  • components/
  • pages/
  • assets/
  • images/
  • fonts/

The components folder is meant for any element that is reusable throughout the project. Headers, footers, styled buttons, etc. The pages folder is meant for... well, pages, like the ones links point to. The assets folder is in the source folder because adding them through javascript has some benefits, like bundling resources for fewer network requests (which speeds up the site). Check out the create-react-app documentation for a full explanation.

File structure — How to organize each piece

The basic file structure has two versions — state-full or state-less. This is an oversimplification (and probably a bad one), so I accept suggestions for replacements.

Stateless Elements

The state-less file structure is meant for elements not responsible for any logic within themselves, but still require styling. Examples would be simple containers, links, images and even buttons. These are components that would work in static pages.

These elements are often reusable and should be put under the components folder. They would require two files: the component.styled.js and index.js. They would be under the components folder. It would go something like:

• src/
  • components/
  • CoolButton/
    • CoolButton.styled.js
    • index.js

WHY?

Using the index structure allows you to omit the the element being imported. This eliminates the ./components/CoolButton/CoolButton.component import path. Instead you get ./components/CoolButton with implied index. (More on this later.) Also, using the CoolButton.styled.js indicates (to you and others) that file is about styling.

• What about using a separate css file instead? It does the same thing!

Styled-components eliminates the necessity to worry about class names. Less decisions equals more brain power! Check out decision-making fatigue.

• What about losing the class selectors? How do you reference elements then?

In that case, you could just add the class names later, as a prop to the component. However, this will likely be unnecessary, due to useRef hooks and the Testing Library grabbing elements by their accessible features.

Small note about index exports

As explained, the index.js is a default entry point of node.js — the thing used by webpack to bundle your project.

An interesting tool for automating index creation is create-index. I haven't tested yet, but I will give it a try.

Stateful Elements

Stateful elements are likely to be pages (or views, or routes), where components are combined and logic is implemented.

The structure would be something like:

• src/
  • page/
  • DataModal/
    • DataModal.styled.js
    • DataModal.js
    • index.js

While statefull elements closely resemble stateless ones in their file structure, there is an addition to the mix — the DataModal.js logic file. This is where you make use of the styled components created at DataModal.styled.js and give them behaviors. If the styled file creates a doll, the logic files gives the doll strings and turns it into a puppet.

How would those files look like?

With this structure, there is the basic pattern of Component.styled.js - index.js - Component.js. Of course, it won't be limited to that (where do tests fit in?!), but it is a nice start.

• Component.styled.js: Here is where the styling comes into place. You will create the stateless components by using the styled-components tag functions like this:

#Component.styled.js
import styled from 'styled-components';

const ModalFrame = styled.div`
  background-color: lightblue;
  font-family: Lato, sans-serif;
  /* --- more styling -- */
`;
// As you can see, it looks just like css, but in js! :D
export { ModalFrame };

• Component.js: Here you make use of stateless components to build stateful ones, like so:

#Component.js
import { ModalFrame } from './Component.styled.js';

const DataModal = () => {
  return <ModalFrame> {/*Some logic inside*/}</ModalFrame>;
};
export { DataModal };

• index.js: It is where the default exporting actually happens. All you need to do is:

#index.js
export { DataModal as default } from './Component'; // './Component.styled' would also work

• All what would be left is to import the component! Since index.js is the default entry point (as seen before), you can just import the directory directly (sorry, I had to):

#SomeView.js
import DataModal from './components/Datamodal'; // Look at that nice import!
// Rest of code

Summary

So, there you have it: a structured way of organizing your project, together with a tiny introduction to styled-components. It is what I will be using for a while now — though I have had my eyes on tailwind for a while. We'll see!

This is my first time writing about software development, so I'm accepting every feedback you guys may have!