Application Structure

[mxstbr]

Changing the application structure might be worth thinking about, right now the thing might seem quite bloated and randomly thrown together for newcomers.

[mxstbr]

Maybe we should have a folder called app, which is the folder you write your application in and only contains the application files and folders, and a folder config (or webpack?) for all the webpack stuff. This would allow us to tell developers to simply write their application in the app folder and write tests in the test folder and don't care about the rest. (should the test folder be inside the app folder?)

The structure of the boilerplate would then be as follows:

app/
|   js/
|   css/
|   img/    <--- maybe rename this to "assets"
|   .htaccess
|   index.html
|   manifest.json
|   serviceworker.js
config/    <--- maybe this should be called "webpack"
|   makewebpackconfig.js
|   server.js
|   webpack.dev.config.js
|   webpack.prod.config.js
docs/
|   COMMANDS.md
|   FILES.md
|   README.md
|   moretocomehere
test/    <--- maybe rename this to "tests"
|   reducers/
|   actions/
.babelrc
.eslintignore
.eslintrc
.gitattributes
.gitignore
LICENSE.md
README.md
package.json

[mxstbr]

I believe having the test (tests) folder inside the app folder makes sense. That way the separation of code-the-user-has-to-write and tooling is complete, and we can tell users they should only care about the app folder and let the boilerplate handle the rest.

The more I think about this structure, the more I like it. It makes using this boilerplate much easier and newcomer friendly. The structure would look like this:

app/
|   js/
|   css/
|   img/    <--- maybe rename this to "assets"
|   test/    <--- maybe rename this to "tests"
|   |   reducers/
|   |   actions/
|   .htaccess
|   index.html
|   manifest.json
|   serviceworker.js
config/    <--- maybe this should be called "webpack"
|   makewebpackconfig.js
|   server.js
|   webpack.dev.config.js
|   webpack.prod.config.js
docs/
|   COMMANDS.md
|   FILES.md
|   README.md
|   moretocomehere
.babelrc
.eslintignore
.eslintrc
.gitattributes
.gitignore
LICENSE.md
README.md
package.json

[mxstbr]

Maybe config is the wrong name for the folder with boilerplate things. That might lead devs to think that they can configure their application in there, which the can't.

Maybe tooling is a better name? I don't want to call it webpack, because there might be other config we want to put somewhere later on.

[swastik]

I think calling it webpack is a good idea because it's very clear. tooling is somewhat ambiguous. You can always change the name later.

img should probably be changed to assets, yeah, because you could add webfonts, etc. that way.

[swastik]

Also, I don't think tests should go inside app. They aren't the "app", technically... nothing there would transpile to the final build. A separate tests folder is fine... it's also probably more visible.

[mxstbr]

Good points. I've implemented this in the v3.0.0 branch, check it out and report any problems you come across!

EDIT: Going to update the docs/FILES.md file soon.

[swastik]

Looks pretty good!

[hampusohlsson]

You could consider bundling the actions, constants and reducers into redux modules and create reducer bundles according to the "ducks" approach.

[mxstbr]

As discussed in #33, having a folder for "smart" components and one for "dumb" components makes a lot of sense. The question is where do pages fit in?

I currently feel like this would be optimal - any other ideas?

app/
|--- js/
    |--- containers/    <--- stateful components
         |--- pages/
    |--- components/ <--- stateless components

[mxstbr]

@hampusohlsson thanks for the link, I'll look into it!

[hampusohlsson]

You can probably put it in a subfolder if you need it. However, my (rather limited) experience with this structure is that page components end up being the only smart ones in the entire app, so you can just keep them under containers to remove the extra level

[philihp]

I would actually be in favor of putting css and javascript. For example:

app/
    components/
               clicker.js
               clicker.css
               switcher.js
               switcher.css

clicker.css is so intimately related to clicker.js that changes to one made by someone new to the codebase should probably want to check out the other file.

Since your build is a webpack bundle, it would also be cool to do this with tests as well. That would alleviate the need to have a tests/ folder that tries to mirror the structure. Most projects don't do this because they transpile the src/ folder, and you don't want that to include tests. Webpack is smarter about this.

[mxstbr]

I'm considering switching to this layout, as it makes a lot of sense for bigger applications. No tests/ and no css/ folders anymore:

app/
|- assets/
|- js/
|  |- components/
|    |- NavBar/
|      |- NavBar.react.js
|      |- NavBar.css
|      |- NavBar.test.js
|    |- Button/
|      |- Button.react.js
|      |- Button.css
|      |- Button.test.js
|  |- containers/
|    |- HomePage/
|      |- HomePage.react.js
|      |- HomePage.css
|      |- HomePage.test.js
|- .htaccess
|- index.html
|- manifest.json
|- serviceworker.js

With CSS Modules importing the CSS files of each component in the .react.js file. Webpack's css-loader (which we use anyway) has support for CSS modules, so it wouldn't be hard to switch.

Where do vendor CSS files and global CSS files (e.g. variables.css, typography.css,...) now fit in?

[zavelevsky]

in that case - 'js' is not a good name for the parent folder 😄
Also - why not 'jsx' extensions for files containing jsx? Looks nicer than '.react.js'.

[mxstbr]

True - any ideas for a better name for the parent folder?

To be honest, I can't remember why I adopted that naming. Submitted a new issue for this, see #50

[zavelevsky]

This is my project structure. Hopes it helps.
Whenever you see a file with .dev. in its name you know I alternate dev/production version of this file using NormalModuleReplacementPlugin.

.
├── build (bundled files for production server)
├── lib
│   └── dev_server.js
├── package.json
├── src
│   ├── fonts (I like to provide everything from my server since it's better for on-premise installations)
│   ├── images
│   │   ├── app_logo.png
│   │  └── favicon.ico
│   ├── js
│   │   ├── api (server communication. 
│   │   │   ├── MOCK_DATA.js
│   │   │   ├── WebApi.dev.js (NormalModuleReplacementPlugin loads this on dev build - so I can get mock data for my "server calls"
│   │   │   └── WebApi.js
│   │   ├── constants
│   │   │   └── AppConstants.js
│   │   ├── core (wraps the state object)
│   │   │   ├── consts.js
│   │   │   └── core.js
│   │   ├── react
│   │   │   ├── components
│   │   │   │   ├── DateSpan.jsx
│   │   │   │   └── VisibilityFilter.jsx
│   │   │   ├── containers
│   │   │   │   ├── App.jsx (using Root helps keeping the App clean)
│   │   │   │   ├── DevTools.jsx
│   │   │   │   ├── Root.dev.jsx (split to dev and prod for different redux store initialization)
│   │   │   │   ├── Root.jsx
│   │   │   │   └── GalleryPage.jsx
│   │   │   ├── helpers
│   │   │   │   ├── canvas.js
│   │   │   │   └── state.js
│   │   │   └── main.jsx (entry point)
│   │   ├── redux
│   │   │   ├── actions
│   │   │   ├── constants.js
│   │   │   ├── helpers
│   │   │   │   └── create_reducer.js
│   │   │   ├── middleware
│   │   │   ├── persistence
│   │   │   ├── reducers
│   │   │   └── store
│   │   │       ├── configureStore.dev.js
│   │   │       └── configureStore.js
│   │   ├── routing
│   │   │   ├── constants.dev.js
│   │   │   ├── constants.js
│   │   │   ├── history.js
│   │   │   └── utils.js
│   │   └── utils
│   │       ├── JsonUtils.js
│   │       └── interval.js
│   ├── styles
│   └── templates
│       └── main_template.html
├── test
└── webpack.config.js

[hampusohlsson]

As image assets also are part of the "source", I usually make one directory called src that contains everything that will be processed by webpack. This is my own preference, but I like to name the js-files inside the components just index.js because that allows you to do something like this from another component:

// Importing a button from the IndexPage would look like this
import Button from '../../components/Button' 

and inside Button/index.js you would import the styles

// Include the styles
import styles from './style.scss' 

Images would obvioulsy have to be imported from the assets folder

import Icon from '../../assets/images/icon.png'

Here's an example of how I've structured one project (a bunch of stuff omitted for brevity)

├── dist
│   ├── css <-- webpack extracted css goes here
│   ├── img <-- webpack processed images goes here
│   └── js <-- webpack compiled js goes here
└── src
    ├── assets
    │   ├── images
    │   └── scss <-- global css such as vendor, variables and typography
    ├── components
    │   ├── Button
    │   │   ├── index.js
    │   │   └── style.scss
    │   └── Table
    ├── containers
    │   └── IndexPage
    └── redux <-- ducks goes in here

In the same manner, it would make a lot of sense to just add a file called test.js for every component. This way, we create a standardized way of how every component should look while keeping it simple. The name of the component is the folder name, which contains an index.js file, a style.css and a test.js file.

Re the global css; right now I'm combining the scss files that contains overall layout, variables and typography into one scss file called base.scss which I'm requiring in the file where I define my routes.

[mxstbr]

@zavelevsky that's very helpful, thanks! What do the constants.js in the routing folder do?

@hampusohlsson We have the app/ folder, which is like your src/ folder, and the build/ folder, which is like your dist/ folder. 👍
I've thought about doing the index.js thing, but it's non-obvious for beginners that it gets exported by default. We have a lot of magic happening already, so I'd rather leave it as it is for now.
I agree with the tests next to the components, that sounds good! It's dependent on #11 though, I have yet to find a nice way to unit test components... (@philihp pinged me on twitter about airbnb/enzyme which looks really nice. I hope he tries implementing it!)

This is what I'm currently looking at:

app/
|- assets/
|  |- img/
|  |- fonts/
|- css/    <--- Global CSS stuff, variables, mixins etc.
|  |- vendor/
|  |- utils/
|  |- main.css    <--- Main CSS file that imports everything
|- js/
|  |- actions/
|    |- AppActions.js    <--- Global Actions
|  |- constants/
|    |- AppConstants.js/    <--- Global Constants
|  |- components/    <--- Stateless components
|    |- NavBar/
|      |- NavBar.react.js     |
|      |- NavBar.css          | <--- Each stateless component has a .css file, a .js file and a .test.js file
|      |- NavBar.test.js      |
|    |- Button/
|      |- Button.react.js
|      |- Button.css
|      |- Button.test.js
|  |- containers/    <--- Stateful components
|    |- HomePage/
|      |- HomePage.react.js           |
|      |- HomePage.css                |      
|      |- HomePage.test.js            | <--- Each stateful component has the same files as the stateless ones
|      |- HomePageActions.js          |      and some actions, some constants and a reducer
|      |- HomePageConstants.js/       |       
|      |- HomePageReducer.js          |
|  |- reducers/
|    |- RootReducer.js    <--- Global Reducer
|- .htaccess
|- index.html
|- manifest.json
|- serviceworker.js

Still not sure what to rename the js/ folder to. Maybe react/ or redux/? Whats the best name, for both advanced developers who know whats going on and beginners who have no idea?

[hampusohlsson]

@mxstbr did not know about enzyme, looks good!

Regarding the renaming of the folder, I think it is hard to satisfy all developers, but I would not recommend using redux. There is another boilerplate erikras/react-redux-universal-hot-example, which uses redux for the ducks. As your project is gaining traction (congrats!) you have the opportunity to influence the recommended way of building redux apps. Especially for newcomers that might have seen the other repo, I think it would be a good idea to not mix it up too much as it will be confusing.

[mxstbr]

A few thoughts later:

app/
|- assets/
|  |- img/
|  |- fonts/
|- global/    <--- Can also put global actions/reducers/... in here as well
|  |- css/
|     |- vendor/
|     |- utils/
|     |- main.css
|- components/
|  |- NavBar/
|     |- NavBar.react.js
|     |- NavBar.css
|     |- NavBar.test.js
|  |- Button/
|     |- Button.react.js
|     |- Button.css
|     |- Button.test.js
|- containers/
|  |- HomePage/
|     |- HomePage.react.js
|     |- HomePage.css
|     |- HomePage.test.js
|     |- HomePageActions.js
|     |- HomePageConstants.js    
|     |- HomePageReducer.js
|- .htaccess
|- index.html
|- manifest.json
|- serviceworker.js

Main changes:

• No need for separate global actions/reducers/constants folders, lets put all of those plus the global CSS folder in a global/ folder.
• No need for another wrapping folder around containers and components, those can live comfortably in the root folder

This one is much cleaner and smaller, while keeping the functionality fully intact.

The only question remaining for me is, where do we put app.js and rootReducer.js? In the global/ folder, hidden behind a wall?

[mxstbr]

I just noticed that pages can be both stateless or stateful. E.g. NotFoundPage and ReadmePage are stateless, while HomePage is stateful. Maybe we do need a seperate folder for pages? I'd like to keep them together if possible.

EDIT: Also, we should add a tests folder to the container folders, otherwise you end up with way too many files in there. An example stateful component, HomePage, would thus look like this:

HomePage/
|- HomePage.react.js
|- HomePage.css
|- HomePageActions.js
|- HomePageConstants.js
|- HomePageReducer.js
|- tests/
|  |- HomePageActions.test.js
|  |- HomePageReducer.test.js

[mxstbr]

I've switched the v3.0.0 branch of this repo to the above application structure and made it work. Have a look (or simply read through the comments above) and tell me what you think!

[hampusohlsson]

Hey @mxstbr, some first impression feedback on your structure. What is the reasoning behind having the HomePage{action,constants,reducers} together with the component (btw, using the ducks approach you would combine everything in one file)? What if you want to dispatch a common action that lives in the HomePage folder from another component, then you would have to either duplicate the actions or remember which component has the actions and include that.. feels a bit dirty 😛

Also, I would not put the redux root-reducer in the same folder as the css (why not put the css folder inside assets :) images are "global" too in a sense, as they can be included from anywhere).

A suggestion is to rename global to something that contains all reducer stuff such as reducers/ducks/redux, and move the css to assets.

├── assets
│   ├── images
│   ├── fonts
│   └── css
│       ├── vendor
│       ├── utils
│       └── main.css
├── components
├── containers
└── reducers
    ├── HomePage
    │   ├── HomePage.js
    │   └── HomePage.test.js
    └── index.js <-- root reducer

In this case your root reducer could look something like this

import { combineReducers } from 'redux';
import { routeReducer } from 'redux-simple-router';

// Custom reducers
import HomePageReducer from './HomePage/HomePage';

// Combine all into one
export default combineReducers({
    HomePage: HomePageReducer,
    routing: routeReducer
});

// Expose individual reducers
export const HomePage = HomePageReducer;

This would allow you to use the following imports

// Import HomePage reducers
import { HomePage } from '../reducers'

// Import the root reducers
import RootReducer from '../reducers'

I know you are not too fond of naming files index.js in favor of easy to understand for newbies ;) But it is a very common pattern when doing module development in Node.js, so why not utilize the feature and add it to repo documentation instead.

[mxstbr]

@hampusohlsson thanks so much for checking it out and posting this amazing feedback!

---

You're right about, I'm not fond of the global/ folder either so I'm going to remove it and simply not have any global CSS. (See the discussion in #32) Not entirely sure where to put normalize.css yet...

I agree that the root reducers shouldn't be there either, I'm just going to put it in the root next to the app.js I think.

---

The reasoning behind having the {actions,reducers,constants} in the same folder as the component:

Imagine you have a NavBar, that has an action openNav and an action closeNav. (with the corresponding constants) In the HomePage, you'd then do the following:

import { openNav, closeNav } from '../NavBar/NavBarActions.js';

Now you can open and close the NavBar from the HomePage! Which (in my mind) makes a lot of sense. The openNav does something with NavBar, so the action should be there.

I'm not sure one should ever have global actions. Do you have an example of an action that doesn't belong to a specific component?

[hampusohlsson]

@mxstbr in your case, I agree it makes sense to put the navbar specific actions together with the NavBar component!

An example I'm thinking of is where you need to fetch/update a bunch of data from the server, e.g. populating a list of users. This list of users could be rendered in multiple components, and actions taken on that list from multiple places. Not sure where that kind of functionality should go.

Perhaps it is the same discussion as with global css 😛 99% of the time we're going to end up having everything local alongside the component, but then you have a couple of edge cases where you need something to be available globally.

[zavelevsky]

I strongly advise against mixing redux actions with components. You should
completely separate them. Passing action creators via props enables you to
put as many abstractions as you'd like between actions and what the
component sees as callbacks. Actions can be called by different components,
e.g. a refresh action can be called by clicking a button or dispatched by
another action.
On Dec 29, 2015 3:53 PM, "Max Stoiber" notifications@github.com wrote:

@hampusohlsson https://github.com/hampusohlsson thanks so much for

checking it out and posting this amazing feedback!

You're right about, I'm not fond of the global/ folder either so I'm
going to remove it and simply not have any global CSS. (See the discussion
in #32 mxstbr#32) Not
entirely sure where to put normalize.css yet...

I agree that the root reducers shouldn't be there either, I'm just going

to put it in the root next to the app.js I think.

The reasoning behind having the {actions,reducers,constants} in the same
folder as the component:

Imagine you have a NavBar, that has an action openNav and an action
closeNav. (with the corresponding constants) In the HomePage, you'd then
do the following:

import { openNav, closeNav } from '../NavBar/NavBarActions.js';

Now you can open and close the NavBar from the HomePage! Which (in my
mind) makes a lot of sense. The openNav does something with NavBar, so
the action should be there.

I'm not sure one should ever have global actions. Do you have an example
of an action that doesn't belong to a specific component?

—
Reply to this email directly or view it on GitHub
mxstbr#27 (comment)
.

[mxstbr]

@zavelevsky interesting, I don't fully agree though. (to be clear, I'm unhappy with the current v3.0.0 structure as well)

As shown above, you can easily import a NavBar action from somewhere else, and contextually it makes more sense for actions that influence a component to be directly next to said component.

The problem of global actions/reducers/..., like the very common data-fetching pattern, still persists. Maybe we could rename the current App container to Wrapper (or something like that), have it not render anything at all except { this.props.children }, and be responsible for global stuff like fetching data and global styles?

[zavelevsky]

Additional arguments against placing actions with components :

• forces a bottom-up way of thinking when designing your application -
  while redux encourages you to first think of your state and the things that
  modify it and then start creating components (top down). You can use TDD
  and fully cover your redux parts with unit tests before even writing a
  single component.
• you couple components and actions, or at least use a structure that
  encourages it.
• props exist for a reason. They are your means to provide data and
  functionality to your components in a way that doesn't make any assumptions
  regarding how you manage your state. A component expects a callback. You
  determine the concrete implementation of this callback elsewhere.
  • action creators belong together. They are aware of each other's
    implementation and aware of state. They are redux entities. They serve as
    the interface of the state and as its concrete implementation. Therefore
    they shouldn't be scattered with components.
    On Dec 29, 2015 7:16 PM, "Max Stoiber" notifications@github.com wrote:

@zavelevsky https://github.com/zavelevsky interesting, I don't fully
agree though. (to be clear, I'm unhappy with the current v3.0.0 structure
as well)

As shown above, you can easily import a NavBar action from somewhere
else, and contextually it makes more sense for actions that influence a
component to be directly next to said component.

The problem of global actions/reducers/..., like the very common
data-fetching pattern, still persists. Maybe we could rename the current
App container
https://github.com/mxstbr/react-boilerplate/tree/v3.0.0/app/containers/App
to Wrapper (or something like that), have it not render anything at all
except { this.props.children }, and be responsible for global stuff like
fetching data and global styles?

—
Reply to this email directly or view it on GitHub
mxstbr#27 (comment)
.

[hampusohlsson]

@zavelevsky thanks for pointing our the difference, did not think about top-down vs bottom-up approach before. Top down is what makes sense to me, keeping all state management code together.

[vramana]

I started out with a containers and dumb components approach but it didn't scale well as kept adding more and more routes and subroutes. My dumb components folder grew too much that it takes a few seconds for me find what I want. I think the approach proposed by @ryanflorence https://gist.github.com/ryanflorence/daafb1e3cb8ad740b346/ works best when you are building a large app.

[mxstbr]

@vramana agreed, that looks very nice for massive apps, but I think it's too convoluted for small to mid size apps.

There's gotta be a middle ground somewhere which works for small apps and scales well...

[CrocoDillon]

While I agree with the arguments against placing components together with redux stuff there are arguments for as well.

If you want to consider large apps I imagine you want to keep stuff modular so different people can work on different parts of the app. Where I work for example each part (called a widget) lives in its own repo with its own template, js, css and tests. We have close to 100 widgets. Nothing React/Redux though but just as an example.

A setup like this not only enables multiple repository for large companies but also enables sharing over npm for anyone.

I'm not sure yet what folder structure I prefer, just saying there are arguments for both :)

[vramana]

@mxstbr Then it should be noted in the README that this might not be the right architecture for starting massive applications. Otherwise they will have to lot of refactoring like me if they every want to switch.

[mxstbr]

To elaborate on my short reply above:

I tend to agree with @zavelevsky that a top-down approach makes more sense when thinking in Redux, so separating the actions, constants and reducers from the components might not be a bad idea after all. This would also allow for global actions, constants and reducers, e.g. for data fetching.

Example:

app
├── actions
│   ├── NavBarActions.js
│   ├── AppActions.js    <--- Global things
│   └── tests
│   │   ├── NavBarActions.test.js
│   │   └── AppActions.test.js
├── assets
├── constants
│   ├── NavBarConstants.js
│   └── AppConstants.js
├── components
│   ├── NavBar
│   │   ├── NavBar.css
│   │   ├── NavBar.test.js
│   │   └── NavBar.react.js
├── containers
│   ├── HomePage
│   │   ├── HomePage.css
│   │   ├── HomePage.test.js
│   │   └── HomePage.react.js
├── reducers
│   ├── index.js    <--- Root Reducer, imports all reducers and combines them
│   ├── NavBarReducer.js
│   ├── AppReducer.js
│   └── tests
│   │   ├── NavBarReducer.test.js
│   │   └── AppReducer.test.js
├── app.js
├── index.html
├── manifest.json
└── serviceworker.js

I still believe the separation of stateful and stateless components makes sense, but I also believe it doesn't scale very well. (like @vramana said above)
I like @ryanflorence's nested approach, but I don't think it's very useful for small to mid scale apps as there are quite a few folders that might not be necessary.

Does anybody have an idea how to combine those two approaches to create a new structure? (Or maybe throw away both of them and create a new one?)
It should be compact for small applications with maybe a handful of components, yet scale well to massive applications with potentially hundreds of pages and thousands of components while staying easily overseeable and useable the whole time.

[ezekielchentnik]

I prefer to keep it simple and consistent. I also like matching typical flux folder structure for easy mapping of concepts (facebook examples). My boilerplate is meant to be used to keep consistency across apps spawned by multiple separate teams. I also have to teach/train devs.

Also, if someone prefers Alt.js, or pure flux as opposed to redux, for the most part, the folders will map and make sense, less cognitive overload... in other words, from react/flux implementation to implementation there is some consistency. the /dist folder is also important, it looks like a normal static website folder. of course, we're also not generating universal apps, but SPAs, and have multiple platforms the apps need to live on, so producing a static /dist that is portable, is important.... hope this helps. https://github.com/ezekielchentnik/react-redux-boilerplate

├── dist                    # built dist, can live anywhere (node, http://surge.sh/, whatever ...)
│   └── css                 
│   └── images              
│   └── js                  
│   └── index.html          
├── src                     # source
│   └── css                 # css/sass, compiled w/postcss
│   └── images              # .png,.svg,.gif optimized w/webpack
│   └── js                  # react/redux source
│     ├── actions           # redux actions, w/thunk
│     ├── components        # react components
│     ├── constants         # constants
│     ├── containers        # containers
│     ├── reducers          # reducers
│     ├── selectors         # selectors, using reselect
│     ├── store             # store, w/devtools & prod config
│     ├── utils             # utilities/helpers, support immatable
│     └── index.js          # app entry
│   └── index.html          # app shell
├── test                    # tests
│   └── *.js                # specs
│   └── setup.js            # jsdom config
├── .babelrc                # babel config
├── .eslintrc               # eslint config
├── .gitignore              # git config
├── devServer.js            # webpack/express dev server
├── LICENSE                 # license info
├── package.json            # npm
├── README.md               # installation, usage
├── webpack.config.dev.js   # config for dev, hot loading, devtools, etc.
└── webpack.config.prod.js  # config for prod, minification, etc.

[vramana]

@mxstbr If you think about it ryan's approach works for small apps as wells we just need not show all that nesting. We just stop at the first level.

[ezekielchentnik]

i agree with @CrocoDillon comment, if there are truly sharable components, treat as such.

[mxstbr]

I think the latest structure above is quite good.

It works for small applications, preserves the differentiation between stateful and stateless react components, and, for larger applications, switching to the nested structure by @ryanflorence is trivial. (Rename root components folder to shared and nest the containers inside each other. This could easily be documented in the AdvancedPatterns documentation I want to add, see #14)

---

I've been thinking about the naming of the a/c/r. We could name the a/c/r with a dot in the name, e.g. NavBar.actions.js, NavBar.constants.js and NavBar.reducer.js and, using the import-glob webpack loader, the rootReducer.js would look like this:

import reducers from "./**/*.reducer.js";
import { combineReducers } from "redux";

const rootReducer = combineReducers(reducers); // Haven't tried this, but it should work

export default rootReducer;

Which means new reducers are automatically added to the store. More magic for beginners, but a bit of a time saver and easily explainable.

---

I'm still on the verge about putting the actions/constants/reducer (a/c/r) next to the container.
On one hand, it would enable truly decoupled stateful components which can be shared across applications and nice imports like

import { openNav, closeNav } from "../NavBar/NavBar.actions";

On the other hand, global a/c/r won't have a place to be.

I think putting the a/c/r next to the container and introducing a global folder is the way to go.

---

Putting all of those thoughts together leaves us with this app structure:

app
├── assets
├── components      # Stateless React components
│   ├── Button
│   │   ├── Button.css
│   │   ├── Button.react.js
│   │   ├── Button.test.js
├── containers      # Stateful react components...
│   ├── NavBar      # ...with component-sepecific actions, e.g. openNav, closeNav...
│   │   ├── NavBar.css
│   │   ├── NavBar.react.js
│   │   ├── NavBar.actions.js
│   │   ├── NavBar.constants.js
│   │   └── test
│   │   │   ├── NavBar.test.js
│   │   │   ├── NavBar.actions.test.js
│   │   │   └── NavBar.reducer.test.js
│   ├── HomePage    # ...or without actions
│   │   ├── HomePage.css
│   │   ├── HomePage.test.js
│   │   └── HomePage.react.js
├── global          # Global a/c/r for data fetching and other edge cases
│   ├── global.actions.js
│   ├── global.constants.js
│   └── global.reducer.js
├── rootReducer.js
├── app.js
├── index.html
├── manifest.json
└── serviceworker.js

Thoughts?

[babeard]

Are there any drawbacks to having a less verbose structure?

It seems a little redundant to have a file named NavBar.actions.js already residing within the NavBar directory. Thoughts?

.
.
.
├── containers      
│   ├── NavBar
│   │   ├── style.css
│   │   ├── component.js
│   │   ├── actions.js
│   │   ├── constants.js
.
.
.

(sorry if this has already been discussed and explained elsewhere)

[mxstbr]

@babeard I don't think it has, thanks for pointing that out!

I'll tell you my reasoning: If you open two actions.js in your IDE, how do you know which ones which? If you call one of the NavBar.actions.js and the other one App.actions.js, it's immediately clear without opening the file.

Note: Good IDEs/Editors (e.g. Atom) will, in the case above, show the file path in the tab, but we have no control over the development environment of the users of this boilerplate, so I'd rather be verbose.

[zavelevsky]

I have to say that the feature separation is a weak argument IMO. Cross
team collaboration can be coordinated and isolated by other means like
source control and some common practices.
It makes so much more sense to me to keep actions together, as they can
dispatch each other.

I think it will make the initial project structure much easier to grasp.
Remember this is a boilerplate, therefore meant to be used for early stage
projects and allow them to grow properly. The optional future transition to
structurally oriented actions and reducers can be documented.

Having said that, in case my opinion isn't accepted, I think your proposal
is pretty good. I assume you omitted some reducers and actions by mistake.
Also, don't expect to reuse statefull components. They should be thin
wrappers and tend to be very applicative (dirty, all knowing).
On Dec 30, 2015 6:01 PM, "Max Stoiber" notifications@github.com wrote:

I think the latest structure above is quite good.

It works for small applications, preserves the differentiation between
stateful and stateless react components, and, for larger applications,
switching to the nested structure by @ryanflorence
https://github.com/ryanflorence is trivial. (Rename root components
folder to shared and nest the containers inside each other. This could
easily be documentation in the AdvancedPatterns documentation I want

added, see #14 mxstbr#14)

I've been thinking about the naming of the a/c/r. We could name the a/c/r
with a dot in the name, e.g. NavBar.actions.js, NavBar.constants.js and
NavBar.reducer.js and, using the import-glob
https://www.npmjs.com/package/import-glob webpack loader, the
rootReducer.js would look like this:

import reducers from "./*/.reducer.js";import { combineReducers } from "redux";
const rootReducer = combineReducers(reducers); // Haven't tried this, but it should work
export default rootReducer;

Which means new reducers are automatically added to the store. More magic

for beginners, but a bit of a time saver and easily explainable.

I'm still on the verge about putting the actions/constants/reducer (a/c/r)
next to the container.
On one hand, it would enable truly decoupled stateful components which can
be shared across applications and nice imports like

import { openNav, closeNav } from "../NavBar/NavBar.actions";

On the other hand, global a/c/r won't have a place to be.

I think putting the a/c/r next to the container and introducing a global

folder is the way to go.

Putting all of those thoughts together leaves us with this app structure:

app
├── assets
├── components # Stateless React components
│ ├── Button
│ │ ├── Button.css
│ │ ├── Button.react.js
│ │ ├── Button.test.js
├── containers # Stateful react components...
│ ├── NavBar # ...with component-sepecific actions, e.g. openNav, closeNav...
│ │ ├── NavBar.css
│ │ ├── NavBar.react.js
│ │ ├── NavBar.actions.js
│ │ ├── NavBar.constants.js
│ │ └── test
│ │ │ ├── NavBar.test.js
│ │ │ ├── NavBar.actions.test.js
│ │ │ └── NavBar.reducer.test.js
│ ├── HomePage # ...or without actions
│ │ ├── HomePage.css
│ │ ├── HomePage.test.js
│ │ └── HomePage.react.js
├── global # Global a/c/r for data fetching and other edge cases
│ ├── global.actions.js
│ ├── global.constants.js
│ └── global.reducer.js
├── rootReducer.js
├── app.js
├── index.html
├── manifest.json
└── serviceworker.js

---

Thoughts?

—
Reply to this email directly or view it on GitHub
mxstbr#27 (comment)
.

[babeard]

@mxstbr Good point.

And of course this kind of decision can be made when you create your components. I personally prefer typing less by default.

import { action } from "../NavBar/actions";
// vs
import { action } from "../NavBar/NavBar.actions";

Keep up the good work!

[hampusohlsson]

@babeard like you, I also think it is too verbose to name both the folder and the files the same thing.

Also, how about the ducks approach? Curious what is the benefit of having 3 separate files or folders for actions/constants/reducers?

[CrocoDillon]

@babeard and others, whatever the file names in the NavBar folder are, if you make NavBar/index.js that re-exports all the things it can probably make your life even easier.

import NavBar, { reducer, action } from '../NavBar';

[mxstbr]

@zavelevsky yes, the current structure is "more standard", that's true - that doesn't mean it's the best approach possible though. We now have to opportunity to influence the way redux applications are structured, and I want to make sure we get this right.

I don't agree stateful components won't be reused - imagine a common NavBar across several websites of a company - it'll be stateful with actions and a reducer, and can easily be shared by making it a npm module or simply copy & pasting it.

---

@hampusohlsson While the ducks approach is quite nice, it's unusual and most redux tutorials will teach you to keep these variables in different files. Suddenly having all of them in one file might confuse beginners, especially with the very specific exports required to make it work.

This reminds me, the whole export and import modularisation should probably be documented, added to #14!

---

Note: I've opened a Gitter chatroom for quicker discussions, join here!

[hampusohlsson]

Regarding the current state of redux tutorials, what I found out in November is that the tutorials from September were already outdated. The ecosystem is moving crazy fast and I don't think we should get stuck in previous best practises. Keep pushing everything forward instead! Will check out the gitter chatroom next week, nice one.

[mxstbr]

@hampusohlsson that's true. Hmm...

[philihp]

I'm confused as to why Components and Containers need associated Actions to them. They aren't 1:1 mapped (in the way that a component would have tests only for it, or styles only for it). Multiple different components could trigger an action, as well as your something in async middleware... I would keep them in their own folder.

[mxstbr]

@philihp That's true, but as I posted above, imagine a NavBar component that has an openNav and a closeNav action. It makes sense to import them from the NavBar directory:

import { openNav, closeNav } from "../NavBar/NavBar.actions";

instead of

import { openNav, closeNav } from "../.. /actions/NavBar.actions";

[mxstbr]

@hampusohlsson I've tried the ducks approach, and decided against it. The confusion caused by the very specific needs of that file are too unusual.
I don't see myself putting it as the default way of building apps with this boilerplate anytime soon, but I'll definitely add documentation on how to quickly refactor the boilerplate to be compatible with ducks! (See #14)

---

In the coming days I'll try to build something with the new application structure to get a feel for the usability. (TBD what)

If anybody else has tried it and built something with it, I'd love any and every input/criticism/comment!

Note: To try the new structure, git clone this repo and run git checkout v3.0.0 to get to the v3.0.0 branch. This'll have the currently up to date structure included.

[canvaskisa]

Hey guys, i'd like to share an application structure i've created and working with for a while. I found it very scalable and simple to understand.

I'm using css-modules, so i can keep component's styles in the same directory as component's logic is (the same is for components tesing).

Units folder is used for simple components like Article, Post, Comment etc.
Catalogs simply wraps Units in array and have some logic like 'load more' buttons.
Pages (or Screens, or Views) are routes for react-router and containers for redux (you can see there is no index.css files nearby). Also they can contain additional directory _, which contains specific components for certain page.
Modules are reusable and complex components (like popups, headers, chats etc), which can also be redux containers and contain _ directory for simplifing component's markup.

├── README.md
├── app
│   ├── actions
│   │   ├── __tests__
│   │   │   └── appActions.spec.js
│   │   ├── appActions.js
│   ├── components
│   │   ├── App.js
│   │   ├── Catalogs
│   │   │   ├── NewsList
│   │   │   │   ├── index.css
│   │   │   │   ├── index.spec.js
│   │   │   │   └── index.js
│   │   │   └── index.js
│   │   ├── Base
│   │   │   ├── Button
│   │   │   │   ├── index.css
│   │   │   │   ├── index.spec.js
│   │   │   │   └── index.js
│   │   │   └── index.js
│   │   ├── Modules
│   │   │   ├── Footer
│   │   │   │   ├── index.css
│   │   │   │   ├── index.spec.js
│   │   │   │   └── index.js
│   │   │   └── index.js
│   │   ├── Pages
│   │   │   ├── AboutPage
│   │   │   │   ├── _
│   │   │   │   │  ├── AboutPageHeader
│   │   │   │   │   │   ├── index.css
│   │   │   │   │   │   ├── index.spec.js
│   │   │   │   │   │   └── index.js
│   │   │   │   └── index.js
│   │   ├── Units
│   │   │   ├── NewsUnit
│   │   │   │   ├── index.css
│   │   │   │   ├── index.spec.js
│   │   │   │   └── index.js
│   ├── constants
│   │   ├── actionTypes.js
│   │   ├── apiEndpoints.js
│   └── reducers
│       ├── __tests__
│       │   └── news.spec.js
│       └── news.js
├── client
│   └── index.js
├── config
│   ├── root.css
│   └── routes.js
├── index.js
├── karma.conf.js
├── package.json
├── public
│   ├── favicon-16x16.png
│   └── manifest.json
├── server
│   ├── index.js
├── utils
└── webpack

I reduced project's tree a lot, but i think it's clear to understand the base concept.
Hope, it will help.

[mxstbr]

@canvaskisa thanks for sharing, I have not seen this split between Units, Catalogs, Pages and Modules before, very interesting!

What exactly are the benefits of this classification? It seems a bit... wobbly, for the lack of a better word. (In the sense that it seems hard to draw an exact line between Catalogs and Modules and, to some extent probably, Units)

[canvaskisa]

@mxstbr Currently i'm working on media apps, and this structure simplifies development lot, in my experience. Of course you can remove such concepts as Catalogs or Units, if there are not much of them in your app, and create something similar.

The main concept is to beware flat structure of your components, categorize them with reusable components (Catalogs, Units) and split into smaller modules (_ directories). This categorization together with setting NODE_PATH, provides clear imports like:

import { Footer } from 'Modules'; 

Also i'd like to add, that i don't think moving stateful components to containers folder is a good idea. It makes directory structure flat, which is bad, in my opinion.

[mxstbr]

@canvaskisa interesting! How do you get those clear imports, did you use resolve.modulesDirectories in the webpack config?

Why do you believe a flat directory structure is inherently bad?

[canvaskisa]

@mxstbr Yeah, resolve.modulesDirectories: ['node_modules', 'components'] will do all the work, additionally you can set aliases for actions, reducers, etc like this:

resolve: {
    alias: {
      constants: path.resolve(__dirname, '..', 'app', 'constants'),
      actions: path.resolve(__dirname, '..', 'app', 'actions'),
      reducers: path.resolve(__dirname, '..', 'app', 'reducers')
    }
}

On the server setting NODE_PATH=.:app:app/components will do the same.

Flat directory structure is ok, but only for small apps. When an app is getting bigger, it's a pain to maintain it with flat structure.

[ravinggenius]

I'm new to this project, so I may be missing something obvious. However I'd like to suggest merging app/components and app/containers. Are they really so different to need such separation?

app
├── assets
├── components      # React components
│   ├── Button
│   │   ├── Button.css
│   │   ├── Button.react.js
│   │   └── Button.test.js
│   ├── NavBar      # ...with component-sepecific actions, e.g. openNav, closeNav...
│   │   ├── NavBar.css
│   │   ├── NavBar.react.js
│   │   ├── NavBar.actions.js
│   │   ├── NavBar.constants.js
│   │   └── test
│   │       ├── NavBar.test.js
│   │       ├── NavBar.actions.test.js
│   │       └── NavBar.reducer.test.js
│   └── HomePage    # ...or without actions
│       ├── HomePage.css
│       ├── HomePage.test.js
│       └── HomePage.react.js
├── global          # Global a/c/r for data fetching and other edge cases
│   ├── global.actions.js
│   ├── global.constants.js
│   └── global.reducer.js
├── rootReducer.js
├── app.js
├── index.html
├── manifest.json
└── serviceworker.js

[mxstbr]

@ravinggenius The problem is that you need some sort of separation between components. If you're building a big application, some day you'll have hundreds of components and having them all in one folder is a pain.

I like the components and containers structure, but it might not be enough. It forces you to think about which components have state and which ones don't, something you think about anyway. It still doesn't scale very well though, and I'm becoming a bigger and bigger fan of Ryan's approach with the nested structure, and it might work fine for small apps. Does anybody have experience building an app like that?

[okonet]

I didn't read it carefully so I might miss something but it seems this thread is mostly concerned about JS and not taking in account CSS and images.

I'm strongly against putting CSS and assets apart from the JS code. The whole point of using PostCSS and CSS-modules is to write components — a dedicated blocks of code which will result in a component look & feel. To make things easy for mainatnace you should always put your assets to the appropriate components. Even if the component doesn't have JS implementation, you should put it into a sub-dir and just require your CSS in the index.js.

Take a look at BEM: https://en.bem.info/method/filesystem/ — this is the idea behind CSS-modules.

[mxstbr]

Yeah, CSS will be next to the JS files. Take a look at the v3.0.0 branch – this is already implemented.

[okonet]

Yes, I saw that and that's cool. But what about non-CSS assets? You still have assets directory, which is bad IMO since it's completely disconnected from the source there these assets are being used. All assets (CSS, images, fonts etc.) should be in the component directory IMO. This the idea of BEM — put all related stuff together. Also this makes requiring images in CSS easy: url("./myImg.png")

[mxstbr]

I didn't think about images at all, but that makes sense. 👍

---

I also think @CrocoDillon and @hampusohlsson were right. I'm not fond of the file-naming anymore:

NavBar
├── NavBar.css
├── NavBar.react.js
├── NavBar.actions.js
└── NavBar.constants.js

I now much prefer this, as its much nicer to import with:

NavBar
├── styles.css
├── index.js
├── actions.js
└── constants.js

This means you can just go import NavBar from 'NavBar';, because with the previous structure you'd have to go import NavBar from 'NavBar/NavBar.react'; which was really annoying.

[okonet]

@mxstbr check mxstbr#103 out

I think verbose file names are good because you'll be looking for stuff in IDE/editor by the name. But to reduce code for imports you could just use index.js file. In case of non-JS components (blocks in terms of BEM) you still could export a JS file with a reuire of CSS (which in turn requires images etc.).

[CrocoDillon]

@okonet, I already mentioned the use of index.js as a proxy for nicer imports before, see mxstbr#27 (comment)

It got overlooked though ;) Whatever the file names are I recommend this approach because you’ll have all exports for a module nicely listed in one small file (index.js).

[mxstbr]

Yeah, you were right it is so much nicer to name them index.js. Added credits to comment above, thanks for reminding me!

[hampusohlsson]

@mxstbr glad you have realized the naming benefit of index.js :)

[mxstbr]

I put the actual components in the index.js instead of simply exporting them from there (one file less!), have been working with this for the past week on a commercial project and I'm loving it.

app
├── app.js
├── components
│   ├── Button
│   │   ├── Button.test.js
│   │   ├── index.js
│   │   └── styles.css
│   └── Img
│       ├── Img.test.js
│       └── index.js
├── containers
│   ├── App
│   │   ├── index.js
│   │   ├── logo.png
│   │   └── styles.css
│   ├── HomePage
│   │   ├── actions.js
│   │   ├── constants.js
│   │   ├── index.js
│   │   ├── reducer.js
│   │   ├── styles.css
│   │   └── tests
│   │       ├── actions.test.js
│   │       └── reducer.test.js
│   ├── NotFoundPage
│   │   └── index.js
│   └── ReadmePage
│       ├── index.js
│       └── styles.css
├── index.html
├── manifest.json
└── rootReducer.js

I still consider that in bad editors users won't be able to differentiate between the index.js, actions.js etc. files. Being held back by those few seems like a bad idea. If their editor can't do it, they can still rename them, but I recon enough people use Sublime/Atom/Brackets/... (which all show the path in the tab)

---

Does anybody have comments about the app structure, something they dislike? Otherwise I'll consider this issue resolved & will close it.

[okonet]

@mxstbr it's not about showing path but about searching for a file. If you know you want to open Button component, you will be typing Button and not index, which will not include your index. So you will have to always type Button/index to open it. I think having one file less in repository isn't worth the pain you'll have every day. This is exactly what @nikgraf was talking about as well.

[mxstbr]

@okonet Ah you're right, I totally forgot about that, damn. Too many reasons for too many things to keep track of...

Thanks for reminding me, I'll have another think about it!

[ravinggenius]

@okonet Vim/Sublime/Atom each can find files via (case-insensitive) fuzzy searches. For instance you can type something like buttinx and be reasonably sure you will find what you're looking for, in this case app/components/Button/index.js. In many cases you can probably get away with typing less.

[nikgraf]

@ravinggenius just my personal experience: we always have a couple components with similar names: Trip, TripRow, Trips. So you don't always want to pick the first and it was just my personal perception, but it felt better once we switched to an index.js separated from the component. The index file can be super simple e.g. export default from './TripRow';

[mxstbr]

I agree with @nikgraf, especially if you're going with the "hardcore" containers there'll be lots of overlap between names.

I just don't think that adding a TripRow.react.js file will fix that, because then you have a TripRow.react.js, a Trip.react.js and a Trips.react.js. That's the same issue as with the index.js, which is that you have to write the full name of what you want, i.e. the question becomes typing Trip.r vs. typing Trip/i.

That doesn't really make a difference, but not having to add an "unnecessary" file each time you create a new component does make a difference, esp. for consistency with multiple devs, so I'm leaning towards the index.js-only-approach.

[mxstbr]

I've decided to go with the index.js approach, for the reasons listed above. If you feel like that's a mistake, please let me know!

I've been working with the boilerplate (non-index.js version) the last week on a commercial product with lots of components and data handling, and I'm very happy with the current structure, so I'm closing this issue. Thanks for the great discussions and inputs everybody, I'm definitely going to link to this issue in the future!

[nareshbhatia]

Sorry for jumping in late, but as I am starting to understand react-boilerplate, I wanted to suggest an alternate approach to application structure that might be more intuitive.

This is what we currently have: all container components under containers and all presentational (or unconnected) components under components. This is widely known as "folder-by-type" structure. Unfortunately it doesn't scale well for even medium-sized applications - components for a single feature will be scattered all over the place. For example, a Dashboard container may have six presentational components sitting under the components folder intermixed with presentational components from other containers. This can quickly get out of hand.

Instead of breaking things by type, wouldn't it be better to break things by feature? Using this approach, the Dashboard component will be a top-level folder with the 6 presentational components under it as 6 child folders. If there is a strong need to distinguish container components from presentational components, the developer can follow some naming conventions similar to those suggested by Dan Abramov in his article, e.g. StoryContainer and Story. Also if there are components that are used in several places, they go under a shared folder. Based on these guidelines, the react-boilerplate example would be structured as follows:

app
 |--- App
 |--- HomePage
 |     `--- RepoListItem
 |--- FeaturePage
 `--- Shared
      |--- List
      |--- ListItem
      `--- ...

This seems much more intuitive to me because it keeps all related components together. What do you think?

[oyeanuj]

FWIW, I have a structure similar to one mentioned by @nareshbhatia except for one change - instead of having a Shared folder, I have the shared components grouped by type of functionality provided by those components, i.e. Buttons, Forms, Cards etc. Currently using it on a medium-large scale application and has scaled well and made my life easier.

[nareshbhatia]

Good to know, @oyeanuj. I have been googling for articles on application structure best practices. Here's two that I found to be very good:

1. Rules For Structuring (Redux) Applications by Jack Hsu
2. Angular2 Style Guide - This one is specific to Angular 2, but it focuses on the same basic issues. I like the structure of this guide because it not only lists the guidelines but also the reasons behind each.