Feature First Organization

Scaling JavaScript apps with feature components

Feature First

I am not going to claim ownership of the idea, but I will tell you about how I came to believe that organizing your applications by feature is the best front-end architecture available.

Search for Perfection

In the search to build the perfect boilerplate for myself and the teams I work with (Hacksmiths and Udacity Alumni), I reverse engineered some of the most popular open source React boilerplates available. Without a shadow of a doubt, the organization pattern followed by the React Boilerplate project is the best. In an attempt to put a name on it, I did some research and I found an article that explained this organizational strategy fairly well.

The article, entitled “Organizing Large React Applications”, calls this type of organization Feature First Organization. They explain that a large application should be a collection of small applications that function in isolation. Wait a minute, this is starting to sound like another architectural pattern known in the Back End ecosystem as “Micro Services”. I think we are onto something here!

In an attempt to switch into the practice of organizing my applications by feature, I created a clone of one of my open source boilerplate projects. I went about reorganizing the structure of the demo application in order to follow the feature first pattern.

Here is an example of the file structure from my boilerplate project:

|   |   ├── containers
| | | ├── FeatureFirstContainer
| | | | ├── tests
| | | | | ├── actions.test.js
| | | | | ├── index.test.js
| | | | | └── reducer.test.js
| | | | ├── actions.js
| | | | ├── constants.js
| | | | ├── index.js
| | | | ├── index.module.scss
| | | | └── reducer.js
| | | └── index.js

You will see that all of the files pertaining to the one FeatureFirstContainer component, including all of the Redux boilerplate, tests and component files exist within one folder. The module takes care of literally everything related to the one feature, in this case a mock container connected to Redux.

Another way to think about this is that there are no files that exist outside of this component that couple it to the application I am currently building. I am not suggesting that you don’t use the component in your app, but when you do use it, you import it as if it were any other module. If you look at this example on Github, you will see that I even include a README.md file with each React Component. Following this approach, I am able to build completely reusable modules and even document them as I go. Brilliant!

I have a few example projects that demonstrates this strategy, by the way. Take a look through the components and connected containers in the link listed above, if you are interested. I also suggest that you take a look at my boilerplate projects (Scalable React TypeScript Boilerplate and Scalable React Boilerplate) to see the difference between these organizational strategies.

Benefits of Feature First

The real benefit as I see it, to this organizational pattern is that you encourage isolation and encapsulation of your UI components. You are literally guaranteeing that your application’s components will be reusable in future projects.

At the end of my projects, I generally will go through the source code to determine what parts of it are reusable, so that I can add them to a UI Kit that I am building. The amazing thing is that as soon as I started using the Feature First organization strategy, ALL of my UI became reusable. It’s truly amazing.

React encourages that you take a functional approach to building UIs. By following a few simple suggestions, your UI can become pure and composable, which is the goal of Functional Programming. Complexity is encapsulated under the hood and your UI becomes a box of legos that you can piece together. I propose that following the feature first organizational strategy is a natural progression of this idea.


The engineers at Facebook realize the benefits of functional abstractions. As far as I can tell, they are taking this approach to the extreme by applying it to their entire architecture. For example, GraphQL is an extension of this abstraction. It collocates data fetching right with your UI components. Using the tools of today, such as Webpack, we can collocate literally everything with our UI: CSS, Images, Data fetching, State Management, etc.

Collocation used to be a horrible idea, but now we see that with the right abstractions, it can be glorious. The big difference, in my opinion, is how we think about architecting our apps today versus then. We have modules baked right into the JavaScript language, the right tooling and a community dedicated to improving this architecture.

By following the feature-first approach, we can get away with collocation and in many ways it makes our applications simpler. Just like the micro-service architecture, we can architect our user interface as a composition of self-contained UI components.

Application in Other Domains

What I hope is that this pattern can be followed in nearly any programming domain and language. The fact that it works with Flux and React so well should be a sign that we are onto something big here that other domains can also benefit from. Any language with a module system can benefit from the feature first architecture.

My hope in writing this article is to spread the knowledge I have gained from following this strategy. If you are a programmer who craves compos-ability, maybe give the feature-first organizational pattern a try in your domain and let us know how it works.


If you are interested like me in the effects of cutting edge functional programming on the JavaScript ecosystem, check out the React Rally talk by Brian Lonsdorf. He is one of the leading Functional Programmers in the JavaScript community and he talks about the beauty of compos-ability.

Another talk that I have also enjoyed was Lee Byron’s Immutable Architecture talk. It gives you a glimpse into how Facebook is using Functional Abstractions in their app architecture.

I hope that these insights have been helpful in your search for the perfect organizational strategy on the web. If so, please tap the heart button below! Many thanks!