How to Structure React Projects

Organize directories per-feature. What is a feature? Think of it as organizing by end-user value delivered. For example, "appointments/", with subdirectories "appointments/recurring/" and "appointments/import/" for those two really complex bits.

Don't make sub-directories by kind (screens/, controllers/, directives/, views/, styles/, etc), instead encode the kind in the filename (make it a suffix).

Don't end up with a system where you end up often making sub-directories that contain only one file. That's likely an unnecessary level.

The rationale is as follows: your system will never have a fixed number of components, but it quite likely will have a fixed number of "kinds of components." So as your system grows, you will have to group files by feature to deal with complexity. When this inevitably happens, it helps not to have a per-kind directory structure to swim against.

By naming your files with name of concern as a prefix and kind as a suffix, you also get related files together by the virtue of sorting files alphabetically in the same folder (monocline grouping).

I don't get the benefit of this approach -- it's too subjective. Is reset-password part of auth or settings feature? What is the link between routes and features? If I'm on a page and see a bug, how do I quickly find the code behind it if it's not linked to the route hierarchy?

The easiest mental model for me is to just map files/folders directly to the route hierarchy. That way you can rapidly build out the overall navigation scheme while building functionality. There are very few subjective decisions besides the route name. New developers can immediately grasp how things are organized and where things belong by interacting with the actual site. If they see a bug, or somebody suggests an improvement on a specific page, they can immediately find the code they'll need to modify.

With features you have to say something like: "Find routes.js, find the route forgot-password within react-router component, see what component it references, now go to top of the file and see the location for that components import. If it's a folder with an index.js file, look in that file and see what component is actually being exported, once you find the underlying component, open that file and try to find the bug."

The reality of business is that it's subjective. That's what we're paid for - to exercise judgment, and make decisions where there isn't a clear right or wrong answer. Anything that's objective can & should be automated. (This also gives a good rule-of-thumb for when & how structure should be imposed on projects: do so when it lets you replace human work with computer work. This is the idea behind convention-over-configuration frameworks.)

Anyway, the practical benefit of a feature-first hierarchy is that it makes the changes you need to add a new feature local to a single directory. This means developers don't need to constantly switch between directories in their terminals & file explorer, it lets you implement mechanisms for automated OWNERS-checking or code review, and it means that commit logs will instantly show which feature they touched just from the filenames.

In practice, "feature" is defined by the org chart: it's one concrete improvement that a specific team is working on to benefit the user.

If you're worried about finding the code for a feature on the screen, add a system where if you hover over any component in the UI, it pops up an overlay with a link to the source code. At a previous workplace, an engineer built such a feature in a couple days and it was an absolute lifesaver.

My current preference is the 'browserify-rails' gem. I set up a package.json file to manage my javascript, but I let the regular asset pipeline handle the css and images. I tried webpack for a while, but it seemed redundant when I already had the asset pipeline.

I also like to add 'babelify' to my package.json and 'config.browserify_rails.commandline_options = "-t babelify"' to my application.rb to get ES6 goodness.

Problem is when one component is used in two or more places. Then it goes in the dreaded "common" directory - a roach motel where files check in but never leave. Also the boundary for what a "feature" is, is likely fuzzy. I haven't seen a large project yet that successfully addresses these issues.