regroup v0.0.2

Regroup

The simple way to get started with React & Redux.

Note: this library is still under early development, so version changes before 1.0.0 might break backwards compatibility. But feel free to try it out and contribute!

Table of Contents

• Why
• Installation
• Example
• API
• Directory Structure

Why?

The current frontend development landscape creates a lot of fatigue.

In some ways this is good, because it means we've arrived at much smaller libraries that can be combined as we see fit, instead of relying on the monolothic giants of the past. But it also means that wiring up all of the small libraries has fallen on our plates, which requires a lot of complex boilerplate code.

Regroup solves this, with a set of sensible, opinionated defaults.

That way you don't have to deal with all of the mundane wiring up of tiny modules. But notice how we call them defaults... That's because although Regroup reduces boilerplate by being slightly opinionated, it doesn't prevent you from customizing things where possible.

Installation

To give you full control over your environment, and the exact versions of the pacakges you use, Regroup doesn't include any of the React or Redux dependencies itself—you're expected to have already installed them.

First install Regroup:

npm install --save regroup

And then, make sure that you have at least these versions installed for all of the React & Redux glue libraries:

npm install --save \
  react@^0.14.0 \
  redux@^3.0.0 \
  history@^1.0.0 \
  react-router@^1.0.0 \
  react-redux@^4.0.0 \
  redux-simple-router@^1.0.0

npm install --save-dev \
  redux-devtools@^3.0.0 \
  redux-devtools-dock-monitor@^1.0.0 \
  redux-devtools-log-monitor@^1.0.0

That's a lot of dependencies, but since you're using Regroup you won't ever have to deal with most of them.

Example

Regroup is just a simple function. You pass in all of our Redux actions, reducers, and middleware, as well as your React components, and it ties them all together for you.

To start, import regroup:

import regroup from 'regroup'

And then import your React and Redux modules:

import * as actions from '../lib/actions'
import * as reducers from '../lib/reducers'
import middleware from '../lib/middleware'
import routes from '../lib/containers'

Then pass them into regroup, returning an object with all of the "wired up" pieces that you might need:

const app = regroup({
  actions,
  middleware,
  reducers,
  routes
})

We call is app just because it's the top-level object that contains all of the moving pieces to your app. One of those pieces is the element property, which contains the React element you'll render:

import { render } from 'react-dom'

render(app.element, document.body)

So the full, basic example that looks something like this:

import regroup from 'regroup'
import { render } from 'react-dom'

import * as actions from '../lib/actions'
import * as reducers from '../lib/reducers'
import middleware from '../lib/middleware'
import routes from '../lib/containers'

const app = regroup({
  actions,
  middleware,
  reducers,
  routes
})

render(app.element, document.body)

Notice how all of the boilerplate around creating a store, applying middleware, and initialize a provider is handled for you.

API

Regroup is just a single function that you call with all of your React and Redux modules—your actions, your middleware, your reducers, your routes, etc.

regroup(options)

regroup({
  actions,
  enhancers,
  env,
  history,
  middleware,
  reducers,
  routes,
  state
})

actions Object

import * as actions from '../lib/actions'

regroup({ 
  actions, 
  ... 
})

An object containing all of the action creators for your application. You can pass your entire lib/actions set of exports here, since Regroup will automatically only touch properties that are functions, so your action constants won't be affected.

enhancers Array

import enhancers from '../lib/enhancers'

regroup({ 
  enhancers, 
  ... 
})

An array of any store enhancers you want to initialize the Redux store with. In development, the Redux Devtools are included for you automatically.

env String

regroup({
  env: process.env.NODE_ENV
})

Defaults to 'development'.

The current environment, for example development or production. This is used to automatically wire up extra development-only dependencies in development, and remove them in production.

Directory Structure

Regroup doesn't strictly enforce a directory structure (for those legitimate edge cases where you can't follow it), but a lot can be gained from following the default one...

We keep all of the "universal" (or "isomorphic") code that revolves around React and Redux in the top-level /lib folder:

/lib
  /actions
  /components
  /containers
  /middleware
  /reducers
  /utils

This makes it easy to see what all of the important universal modules are, for using directly with regroup API. The

We also have two other top-level folders for browser-specific and server-specific code:

/browser
/server

And a few other top-level folders that are already standard:

/bin
/public
/test

Following that simple structure makes it trivial for other developers to jump into your codebase and figure out what's going on.

Resources

Good examples of boilerplate to eliminate:

• http://blog.joanboixados.com/building-a-boilerplate-for-a-koa-redux-react-application-including-webpack-mocha-and-sass/
• https://medium.com/front-end-developers/handcrafting-an-isomorphic-redux-application-with-love-40ada4468af4#.yksjwu4d9
• https://blog.diacode.com/trello-clone-with-phoenix-and-react-pt-2