Maciek Chmura

Posted on May 28, 2019 • Updated on Jul 2, 2020 • Originally published at maciek.cloud

How I structure a React project

#javascript #react

There are many guides on how to structure web apps and React in particular.

Move files into folders based on Smart/Dumb components.
Organise them by the Header/Main/Footer
Or throw everything to Components and combine them in Pages???

I’ve never been fully convinced to use any of these conventions.
And then, about 2 months ago I started a new project. Simple tech stack: React + Express + MySQL.
After a few commits, I had to move the components somewhere.
After a little bit of research, I found something promising.
It's based on 2 resources:

Dan gave me freedom and Brad gave me structure 😅

Atomic Design introduces a new, abstract way to think about project structure. Components are building blocks of an app.
Atoms, molecules, organisms, templates, and pages. This concept brings a breath of fresh air to how we can think about structure.
For my purpose, I used the first 3, but I encourage you to read Brad's guide and adapt it to your liking.

I started with a sketch:

Main idea:
3 folders: Atoms, Molecules, Organisms
If the component has logic/state -> move it to Organisms.
If the component has other components -> move it to Molecules.
Otherwise, the component is an Atom.

I like the organic analogy. It creates a mental and logical box for React components. If needed, I can add more non-organic folders for Utils, Routes, API, etc.
A Button will be in Atoms.
A Card will be in Molecules.
Component with Hooks will be in Organisms.

src/
  Atoms/
    Button
    ProjectName
    ...
  Molecules/
    ControlBar
    DaysList
    ...
  Organisms/
    User
    CreateUser
    ...
  Utils
    formatMonthData.js

For now, this works with no flaws with my project. I will reevaluate this concept when my project grows.

Top comments (16)

Anton Korzunov • May 30 '19 • Edited

I hate this approach. Oh, how I hate this approach.

Let's say - you need a Button.

While you are developing it - it could be clear for you what it is. Probably it is an Atom.
But then you are refactor it, extracting some pieces, and BAM! it shall be a Molecule.
Then you will add some state to it, to track visual state in a fancy way and BAM! it shall be an organism.
Then you reactor it to keep all the "state" in a CSS - you can do it for a button.
And what then? Shall it be atom again? It quaks like an Atom, it's walks like an Atom - IT'S AN ATOM!

Even worse scenario - you have keep this component discoverable. You have to know there to look for it.

Separation shall not be done by how something is made - it's an implementation detail. Separation shall be done by a responsibility you can reason about - screen, page, component, internal component stuff which shall not be ever used outside.

Smart/Dumb component separation is also quite dumb. It's a right separation, but you might have both components if not in one file, then in one directory.

Separation should be made in a way you never would be forced to rename or move your component after refactoring, and it would be always easy to find it. And use. And test.

Maciek Chmura • May 30 '19

Thank you for this strong opinion :)
It is always good to know what are the drawbacks of a given approach.

This idea is a living process.
Thanks to your feedback, maybe we will optimize it, or discover even something better.

Jakub Sarnowski • May 29 '19 • Edited

I've tried this approach and I didn't like it. Mostly because I found it problematic to find the components I was looking for.

For example: imagine a Button with IconButton and ProgressButton variants. In this case, the Button goes to Atoms, IconButton to Molecules (as it contains other components) and the ProgressButton to organisms (as it tracks some progress in the state). Now, it wasn't always clear to me where should I look for the specific component. And this was an even bigger problem for someone who just joined the project. It's a lot easier to have related components next to each other.

(btw. I know that the ProgressButton could just accept progress and be a Molecule, treat it just as an example!)

This wasn't a problem when the project was small, but as soon as it became bigger, it was a lot easier to just put all components into one folder, or just structure them by feature.

But that's just my opinion :D It "feels right" for me - quoting Dan Abramov's words - but everyone feels different :)

Maciek Chmura • May 29 '19

Thanks for this insight ;D
I wonder if I will have the same feeling when my project grows.

K • May 28 '19

Cool idea. I use screens and components, but the components directory gets rather unwieldy xD

GlyphCat • May 29 '19

Same here, tho I have a folder called "modules" which I believe is similar to the Utils mentioned in the main thread.

You could try dividing your components folder (instead of src) using the organic analogy, perhaps that would help?

K • May 29 '19 • Edited

I got

modules
- components
- screens
- utils

The components directory is the biggest, but I'm looking into react-native-elements right now, so maybe this will remove the need for most of my small/dumb components.

adam meier • May 29 '19 • Edited

I like the idea, but personally I dont think the logic|state => Organism rule should be so strict. In my experience there would be many times in which a component such as a form uses stateful logic, but doesn't contain "application specific" logic (I hope that term makes sense), which would make it be more suited as a Molecule rather than an Organism.

Javier Aguirre • May 28 '19

I like this separation, it’s very interesting. The naming is also intuitive.

I use Redux on my projects, so for me Organisms would be connected components.

For Atoms could be PureComponents, that would be a good approach, simplifying its lifecycle.

Raghav • May 28 '19

Cool idea. The pages and other components coexist in Organisms. Have you had any difficulty with the coexistence? I tried multiple ways to structure so far with no luck.
Right now, I use pages, containers, components to structure my project.

Maciek Chmura • May 29 '19

If you like you can add Pages (if they combine multiple Organism). We need to listen to Dan and do what works for us :)
I would suggest you to test it and see how you like it.

Félix Dorn • May 28 '19

if e.g a Card use a CardHeader, the CardHeader should be in atoms in a Card folder or in the molecules folder

Maciek Chmura • May 29 '19

I don' like long import strings, so in my case, I want to have a flat folder structure.
I prefer to not do multiple nestings. So I have only one Atom folder, one Molecules ,etc.
I think that with something like this:

src/
  Molecules/
    Card/
      Atoms/                   << to much nesting for me
          CardHeader

it gets harder to navigate the project.
But please, test it and see if it works for you :)

Saugat Rai • Jun 7 '19

This is really cool.
I aways get confused on how to manage my files on project. Moving files doesn't seems right unless you have a better folder structure.