Awesome Open Source
Awesome Open Source

npm package dependencies


Join the chat at

Reactuate is an opinionated stack for building React/Redux-based frontend applications with a focus on DDD (Domain-Driven Design). The rationale behind this project is to ensure there's a "standard stack" with compatible versions of various libraries stitched together in a cohesive way. This comes at a cost of reduced ability to swap out certain components but ultimately helps shipping software fast.

This is an early version, and some things are in a flux, and some underlying libraries and APIs will change before 1.0.

Next version roadmap


Current published version:



Reactuate is licensed under the terms of Apache 2.0 license.

Table of Contents generated with DocToc

Core Objectives

  1. Fork-and-forget (or fork-and-follow) is not a great way to keep up with what's happening in the original boilerplate (and in the space in general). Therefore, starting off a cloned boilerplate "kit" is not an acceptable solution. Reactuate is distributed as a dependency.
  2. Reactuate is strictly a frontend-oriented stack and is not meant to provide a foundation for so called "universal" (server and client side) JavaScript applications.
  3. Reducing the amount of noise. Many kits suffer from the need to create too many files for each "functional vertical" (such as action creators, constants, reducer), which in turn leads to increased maintenance complexity (try renaming one of the verticals!), import nightmare and inability to have a compact overview of the functionality.
  4. Discovering and learning the capabilities of a comprehensive stack could be complicated. What's worse, maintaining such stacks can be equally painful. Therefore, unconventionally, Reactuate is written as a literate program and is meant to be read as an article and be a concise reference manual — while being a functional library. The effects of this literate program are also included in Reactuate's repository to improve its accessibility. Certain parts of code that do not contribute to the reader's clarity are commented out and therefore omitted from the rendered documentation. They are, however, used for source code production.



Below is a quick reference diagram of the Reactuate stack.



Reactuate requires the following version of Node.js:


More recent versions are allowed, within the upper boundary of the next major version.

In order to produce the extracted source code of Reactuate (should you need it), you will need litpro npm package to be installed. Currently required version:


Building Reactuate is quite simple:

$ make

Getting started

As it has been mentioned before, Reactuate is distributed as a dependency, and can be installed with npm. Assuming you already initialized your project with npm init:

$ npm install --save-dev reactuate
# if you answered 'yes' to the postinstall script:
$ npm start
# otherwise:
$ node node_modules/reactuate/webpack-dev-server.js

Now you can open http://localhost:3000 to run the first application!

Note: The development server port defaults to 3000, but can be configured using PORT environment variable.

The rest of this manual will introduce you to the concepts and software used in the stack. Please note that this stack is developed as a literate program. This means that you'll see excerpts from the stack's code and examples of how you can use these parts. All excerpts are marked with this image: excerpt

Webpack Layer

We serve the application in development mode and package the production version using webpack package npm|[email protected]:

Webpack Configuration

There's normally little to no Webpack configuration tweaking you need to do.

By default, it will assume your index.html to be this:

<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
		<title>Reactuate Application</title>
		<div id="app"></div>

When you are ready to override it, simply copy the above file to the root of your project.

This file will be processed with npm|[email protected].

Reactuate will search for source code files in this directory in your project:


It will assume your main file in that directory to be index.js, and if there is no such file in your project yet, Reactuate will use its own sample file.

All the JavaScript files are going to be process by Babel through the use of npm|[email protected] plugin.

To enable ES2015 syntax and experimental features, the following plugins are required:

To enable React-specific features, a number of Babel plugins is required:

In production builds, following optimizations are used:

Source code builds will be produced into this directory in your project:


When used in development mode, Webpack should use Webpack development server as an entry point and enable hot module replacement,

In production, following HTML processing will be performed:


if (production) {
  plugins.push(new HtmlWebpackPlugin({
    template: index,
    minify: {
      removeComments: true,
      collapseWhitespace: true,
      removeRedundantAttributes: true,
      useShortDoctype: true,
      removeEmptyAttributes: true,
      removeStyleLinkTypeAttributes: true,
      keepClosingSlash: true,
      minifyJS: true,
      minifyCSS: true,
      minifyURLs: true
    inject: true

Reactuate's Webpack configuration will define the location of the reactuate module as REACTUATE_DIRNAME variable in the target runtime.

In production, it will produce compacted and somewhat obscured JavaScript (no source map to avoid divulging original source code's information).

It will also set process.env to your host's process.env.NODE_ENV (if none specified, then it will be assumed to be development).

Reactuate enables ES2015, react/react hot module replacement, and stage-0 presets.

What's important, since babel-loader will not use local .babelrc to merge options, Reactuate will read .babelrc (but not babel configuration from package.json yet) and merge it with its own defaults (it will use npm|[email protected] for that).

By default, .babelrc takes precedence (this also means that arrays specified in .babelrc are appended to those in defaults). If the precedence needs to be flipped (for example, certain presets need to be invoked before the default ones), .babelrc.default file can be used instead of (or in addition to) .babelrc

It will also enable source maps in development.

Reactuate also allows importing JSON files with json-loader npm|[email protected].

Reactuate allows importing CSS files with npm|[email protected] npm|[email protected], npm|[email protected] with npm|[email protected]. It also includes npm|[email protected], npm|[email protected]. In order to enable globbing in CSS processing in postcss-import, npm|[email protected] is required.

Reactuate allows importing fonts and images with npm|[email protected] and npm|[email protected].

Reactuate also requires npm|[email protected] to allow loading raw files as a string, if necessary, using the "raw!/path/to/file" syntax.

"scripts": {
  "build": "NODE_ENV=production webpack --config node_modules/reactuate/default-webpack-config.js --progress --colors"

You will be able to run it with

$ npm run build

Running a development Webpack server

It is imperative to be able to run an easy to update, hot-reloadable development version of the application before shipping a build. This is what npm|[email protected] does.

In order to start a development Webpack server, you can run:

$ node node_modules/reactuate/webpack-dev-server.js

Alternatively, you can add a convenience helper to your package.json:

"scripts": {
  "start": "node node_modules/reactuate/webpack-dev-server.js"

With this you can simply run the following to start your development server:

$ npm start

Development server


var path = require('path'),
    webpack = require('webpack'),
    WebpackDevServer = require('webpack-dev-server'),
    config = require(path.join(__dirname, 'default-webpack-config')),
    port = (process.env.PORT ? parseInt(process.env.PORT, 10) : 3000)

console.log('Starting server...\n')

new WebpackDevServer(webpack(config), { // Start a server
  publicPath: config.output.publicPath,
  hot: true, // With hot reloading
  inline: false,
  historyApiFallback: true,
  quiet: false,
  proxy: config._config.devProxy
}).listen(port, 'localhost', function (err, result) {
  if (err) {
  } else {
    console.log('Server started')
    console.log('Listening at localhost:' + port)

Language Layer

Babel Layer

Reactuate encourages the use of most recent versions of Babel. Babel is a transpiler from future versions of ECMAScript to JavaScript you can run in the browser today npm|[email protected] (also required as a peer dependency npm-peer|[email protected]).

Babel 6 is still fairly new and unfortunately, not all tools support it well, but this should be less of a problem going forward.

In order to avoid generating plain JavaScript files for this package, we also include babel-register npm|ba[email protected]

ES6 also has new APIs that are provided by npm|[email protected].

Reactuate itself requires the following Babel configuration:


{"presets":["react","es2015","stage-0"], "plugins":["transform-export-extensions"]}

React Layer

Reactuate is a React-based stack, so it naturally depends on npm|[email protected] andnpm|[email protected].

Redux Layer

Part of React's power lies in the associated "Flux" architecture. There are many different implementations of it, and Reactuate is using Redux npm|[email protected] and its React binding npm|[email protected]. To enable asynchronous action creators, we have included npm|[email protected] (however, we promote another way to handle asynchronous operations, more on that later). It also uses npm|[email protected] for logging.

Our own version of createStore takes care of a few things automatically.


import { createHistory }                         from 'history'
import { createStore, applyMiddleware, compose } from 'redux'
import { Provider }                              from 'react-redux'
import thunk                                     from 'redux-thunk'
import { reduxReactRouter, routerStateReducer }  from 'redux-router'
import createLogger                              from 'redux-logger'
import sagaMiddleware                            from 'redux-saga'

import domainMiddleware                          from './domainMiddleware'

export default function(routes, domains) {
  let sagas = []
  for (var domainName in domains) {
    let sagasDict = domains[domainName].get('sagas')
    for (var sagaName in sagasDict) {
  let store = compose(

It enables Saga middleware for complex asynchronous operations orchestration:


It enables serializability of domain actions:


It also enables asynchronous action creators:


And adds logging in the development mode:

        predicate: (getState, action) =>
        (process.env.NODE_ENV === 'development' &&
        action['type'] !== 'EFFECT_TRIGGERED' &&
        action['type'] !== 'EFFECT_RESOLVED' &&
        actionTransformer: (action) => {
          if (action['type'] === '@@reactuate/action') {
            return action.payload
          } else {
            return action

It is important to note that it automatically injects a store enhancer for react-router:

    reduxReactRouter({routes, createHistory})
  return store

React Routing

As a foundation for routing React applications, we use react-router npm|[email protected] (which requires a peer dependency of npm|[email protected]).

We also supplement it with a npm|Redux extension npm|[email protected]. Although this one is less stable, we believe it has more comprehensive functionality comparing to redux-simple-router.

First of all, we want to define a way to create a router-enabled composite reducer:

  • Inject routerStateReducer at router



import { combineReducers }    from 'redux'
import { routerStateReducer } from 'redux-router'

export default function(reducers) {
   if (typeof reducers !== 'object') {
     throw "Reactuate reducers should be an object (and not a function)"
   return combineReducers({router: routerStateReducer, ...reducers})

We also standardize route initialization. This step is hidden from the end user.



import React           from 'react'
import { ReduxRouter } from 'redux-router'
import { Provider }    from 'react-redux'

export default function(store, routes, createElement) {
  return <Provider store={store}><ReduxRouter createElement={createElement}>{routes}</ReduxRouter></Provider>


Many React/Redux applications adopt the following directory layout (or a variation of it):


We find this layout to be very counter-productive comparing to organizing code by domains. It is only marginally better than organizing directories or packages by entity types. Consider doing this in Java:

Does this make a lot of sense to you? Hope not!

Therefore, we propose organizing Reactuate-based applications by domain:


This way you don't need to jump across the hierarchy of the project while working on one domain, and you can easily rename the whole domain without having to rename 4-5 files across the project!


Now we have approached one of the most important aspects of Reactuate. We structure our applications around domains, not types of artifacts.

While JavaScript as a language is quite flexible and doesn't possess a strong type system, there are some great libraries available that solve this problem to an extent. Reactuate applications make a heavy use of npm|[email protected] and its helper module npm|[email protected].

First of all, we need to define a class representing a domain. It is a named container for all things associated with one domain (including, but not limited to, types, action creators, sagas and a reducer).



export default class Domain {

  constructor(prefix) {
    this.prefix = prefix || ""

  withPrefix(name) {
    return (this.prefix == "" ? "" : this.prefix + "/") + name

  withoutPrefix(name) {
    return name.replace(new RegExp(`^${this.prefix}\/`),'')

  register(type, name, value) {
    this[type] = this[type] || {}
    this[type][name] = value

  get(type) {
    return this[type] || {}

Most of the time, you don't need to do anything with the Domain object yourself, except for passing it as a parameter to other Reactuate functions that you'll see below. One significant exception to that is our current convention of "attaching" your types to the domain. Consider this example:

const domain = new Domain("user")

const User = t.struct({
  email: t.String
}, 'User')

domain.User = User

This way you can easily access types from other domains when importing those domains:

import user from '../user'

const Message = t.struct({
  user: user.User,
  message: t.String
}, 'Message')

Every domain begins with a state. We define state with tcomb's help:

import ft from 'tcomb-form-types'

import { t, Domain } from 'reactuate'

const domain = new Domain("counter")
export default domain

const State = t.struct({
  counter: ft.Number.Integer
}, 'State')

In the above example, we are defining a state that has a counter. Now, we should define an increment action. Reactuate offers helper functionality to do so, in adherence with FSA npm|[email protected] guidelines:



import t from 'tcomb'

export default function(domain, action, payload = t.Any, defaultValue = undefined, meta = t.Any) {
  let actionString = domain.withPrefix(action)
  function ActionCreator(value = defaultValue, error = false,
                         metaValue = undefined, path = [payload.displayName]) {

    if ( {
      return value

    value = payload(value)

    if (typeof metaValue !== 'undefined') {
      metaValue = meta(metaValue)

    if (!(this instanceof ActionCreator)) {
      return new ActionCreator(value, error, metaValue, path)

    this.type = actionString
    this.payload = value

    if (!!error) {
      this.error = true

    if (typeof metaValue !== 'undefined') {
      this.meta = metaValue

    if (process.env.NODE_ENV !== 'production') {

  ActionCreator.meta = {
    kind: 'actionCreator',
    payload: payload,
    name: actionString,
    identity: false

  ActionCreator.displayName = `Action ${actionString}(${payload.displayName})`
  ActionCreator.actionCreator = true
  ActionCreator.action = action = x => x instanceof ActionCreator

  domain.register('actions', action, ActionCreator)
  return ActionCreator

Unfortunately, tcomb structures do not fit the definition of a plain object required by redux, so we have to implement a custom middleware that strips the extra metadata.



export default function ({ getState }) {
  return (next) => (action) => {
    if (!!action.constructor.actionCreator) {
      let newAction = {type: "@@reactuate/action", payload: {...action}, meta: {name: action.constructor.action}}
      return next(newAction)
    } else {
      return next(action)

IncrementCounter in the example below is an action creator:

import { createAction } from 'reactuate'

const incrementParameter = t.struct({increment: ft.Number.Integer}, 'incrementParameter')
const IncrementCounter = createAction(domain, 'IncrementCounter',

Reactuate has a helper that allows creating a reducer that (again) makes a good use of tcomb. The syntax that it defines is based on the one from tcomb.match(). After specifying the domain and the initial state, it takes a variadic list of matchers:

createReducer(domain, initialState, ...matchers: Array<Matcher>)

Where each Matcher has the following structure: type, [guard], handler:

  • type is a tcomb type
  • guard is an optional predicate (state, action) => boolean
  • handler is a function that handles the action (state, action) => State

It also takes care of disabling state mutation (however, normally this shouldn't be necessary, if tcomb is used for action creators).



import t from 'tcomb'

export default function(domain, initialState, ...cases) {
  let reducer = (state = initialState, action) => {
    let typedAction = action
    if (action['type'] === '@@reactuate/action') {
      let actionCreator = domain.get('actions')[domain.withoutPrefix(action.payload.type)]
      if (! {
        typedAction = actionCreator(action.payload.payload, action.payload.error, action.payload.meta)
    let stateCases = => {
      if (typeof f === 'function' && typeof f.meta === 'undefined') {
        return (handler) => f(state, handler)
      } else {
        return f
    return t.match(typedAction, ...stateCases, t.Any, () => state)
  domain.reducer = reducer
  return reducer

Now, we can define a reducer this way:

import { createReducer } from 'reactuate'

const initialState = State({counter: 0}, 'CounterState')

const reducer = createReducer(domain, initialState,
    IncrementCounter, (state, action) => {
      let increment = 1;
      if ( {
        increment = action.payload.increment
      return State.update(state, {counter: { $set: state.counter + increment }})

Did you notice we avoided creating the whole layer of 'constants'?

Managing effects

When asynchronous (thunk middleware) action creates are getting too complex, it's a sign that it's time to manage effects in an orchestrated way. We are using redux-saga, npm|[email protected] for that.



export default function(domain, name, saga) {
  domain.register('sagas', name, saga)

The below example shows handling the counter example in an async way (we're introducing a delay as well):

import ft               from 'tcomb-form-types'
import { t,
         take, put }    from 'reactuate'

import domain           from './index'

const asyncDomain = new Domain("counterAsync")

const incrementParameter = t.struct({increment: ft.Number.Integer}, 'incrementParameter')
const IncrementCounterDelayed = createAction(asyncDomain,
                                'IncrementCounterDelayed', t.maybe(incrementParameter))

function delay(millis) {
    return new Promise(resolve =>
      setTimeout( () => resolve(true), millis)

createSaga(asyncDomain, 'IncrementCounterDelayed', function* () {
  while(true) {
     const nextAction = yield take(
     yield fork(function* () {
       yield delay(1000)
       yield put(domain.actions.IncrementCounter(nextAction.payload))

export default asyncDomain

Putting it all together


import t               from 'tcomb'
import ReactDOM        from 'react-dom'

import createStore     from './createStore'
import combineReducers from './combineReducers'
import createRouter    from './createRouter'

export default class Application {

  constructor(properties) {
    this.routes = properties.routes
    this.element = properties.element || document.getElementById('app') = || {}
    this.reducers = {}
    for (var key in {
      if (![key].reducer)) {
        this.reducers[key] =[key].reducer
    if (!!this.routes) {
      this.createElement = properties.createElement = createStore(this.routes,
      this.router = createRouter(, this.routes, this.createElement)

  render() {
    ReactDOM.render(this.router, this.element)

export Application            from './Application'
export Domain                 from './Domain'
export createReducer          from './createReducer'
export createAction           from './createAction'
export createSaga             from './createSaga'
export React                  from 'react'
export { Route }              from 'react-router'
export { connect }            from 'react-redux'
export { bindActionCreators } from 'redux'
export t                      from 'tcomb'

export { takeEvery, takeLatest } from 'redux-saga'
import { effects, utils }        from 'redux-saga'
module.exports = {...module.exports, ...effects, ...utils}

Example Application

You can use it this way (this is the sample file you get by default, by the way!):

import { React, Route, Application,
         connect, bindActionCreators } from 'reactuate'

import counter from './counter'
import counterAsync from './counter/async'

class App extends React.Component {
  render() {
    return <div>{this.props.children}</div>

class HomePage extends React.Component {
  handleIncrement() {
  handleIncrementDelayed() {
  render() {
    return (<div>
     <h1>Reactuate Application</h1>
     Congratulations! You are running a Reactuate application now. Here is what you need to do to start developing your own application:
       <li>Unless you have done so already, add a start script to your package.json:
{`_"Running a development Webpack server:webpack-dev-server-script|trim"`}
        This way you can easily run your application:
{`_"Running a development Webpack server:webpack-dev-server-start"`}
       <li>Also, add this to your package.json
{`_"Webpack Configuration:npm run build"`}
       This way you can easily make a production build of your application:
{`_"Webpack Configuration:npm run build command"`}
       <li>Copy the starter file from {`${typeof REACTUATE_DIRNAME === 'undefined' ? "<reactuate package dir>" : REACTUATE_DIRNAME}/sample/index.js`} to src/index.js</li>
       <h5>Counter example</h5>
       <button onClick={() => this.handleIncrement()}>Increment</button>
       <button onClick={() => this.handleIncrementDelayed()}>Increment with delay</button>

HomePage = connect(state => ({counter: state.counter.counter}),
                   dispatch => ({actions:
                     bindActionCreators({...counter.actions, ...counterAsync.actions}, dispatch)}))(HomePage)

const routes = (
  <Route component={App}>
    <Route path="/" component={HomePage} />

new Application({routes, domains: {counter, counterAsync}}).render()

Appendix 1. Post-Installation Instructions

Reactuate is nice enough to help you finalizing your setup once it is installed. This requires npm|[email protected].

Appendix A. Package file

We process all dependencies declared in this file to produce a list of dependencies for package.json.

Appendix B. .gitignore


Appendix B1. .npmignore

As npm documentation says:

"Use a .npmignore file to keep stuff out of your package. If there's no .npmignore file, but there is a .gitignore file, then npm will ignore the stuff matched by the .gitignore file. If you want to include something that is excluded by your .gitignore file, you can create an empty .npmignore file to override it"

Alternatives To Reactuate
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,122,137
Reactjs (171,026
Plugin (113,429
Redux (28,786
Webpack (23,854
Stack (16,004
Babel (7,984
Preset (3,725