# README
Compose a Redux store out of smaller bundles of functionality.
Created by: [@HenrikJoreteg](http://twitter.com/henrikjoreteg)
Created for and used by PWAs that value small bundle sizes, network resilience, and explicit state management. If you want to be able to declaratively combine seemingly disparate logic such as: if it's the third tuesday of the month, our cached data is more than 3.5 days old, and the user is viewing the `/reposition-satellite` page then trigger a data refresh of satellite position... this toolkit is for you.
If you pair it with [Preact](https://preactjs.com/) it's \~15kb for an entire app toolkit.
If you want to see an app built with it, check out: [anesthesiacharting.com](https://anesthesiacharting.com).
## The basic idea
Organize all Redux-related code into a single flat folder of "redux bundles". A bundle is a single file for each main area of functionality in your app.
A bundle can optionally export things like:
1. A name
2. A reducer
3. Action creators
4. Selectors (functions for reading state)
5. An init method
For example:
`bundles/users.js:`
```javascript
export default {
// the name becomes the reducer name in the resulting state
name: 'users',
// the Redux reducer function
reducer: (state = [], action) => {
// ...
// state here is the "users" slice of full state object
return state
},
// anything that starts with `select` is treated as a selector
// selectors get full state object so they can use state from other bundles
selectActiveUsers: state => state.users.filter(user => user.isActive),
// anything that starts with `do` is treated as an action creator
doUpdateUser: (userId, attrs) => ({ dispatch, apiFetch }) =>
dispatch({ type: 'USER_UPDATE_STARTED' })
apiFetch('/users', { type: 'PUT' }, attrs)
.then(res => {
dispatch({ type: 'USER_UPDATE_FINISHED' })
})
.catch(err => {
dispatch({ type: 'USER_UPDATE_FAILED' })
}),
// optional init method is ran after store is created and passed the
// store object.
init: store => {
// action creators are bound and attached to store as methods
store.doUpdateUser()
// selectors are also "bound" and attached to store as methods
store.selectActiveUsers()
}
}
```
Redux-bundler then composes those "bundles" into a function that returns a ready-to-go Redux store.
Usually you'd just do this in the index file of your bundles directory:
`bundles/index.js:`
```javascript
import { composeBundles } from 'redux-bundler'
import usersBundle from './the/file/above'
import authBundle from './bundles/auth'
// ... import other bundles
export default composeBundles(
usersBundle,
viewportBundle
// ... add bundles here
)
```
Then, in your root component, call the function exported by the bundles directory, pass it any initial data and you're up and running:
`components/root.js`
```javascript
import React from 'react'
import { render } from 'react-dom'
// similar to react-redux
// bindings available for React and Preact
import { Provider } from 'redux-bundler-react'
import App from './components/app'
// the file above exports a ready-to-go
// createStore function
import createStore from './bundles'
// you can also pass it initial data here if you have any
const store = createStore(window.BOOTSTRAP_DATA)
// render your app
render(
,
document.body.getElementById('app')
)
```
Now you can efficiently connect components with way less boilerplate:
`components/some-component.js`
```javascript
import React from 'react'
import { connect } from 'redux-bundler-react'
// pass as many names of selectors or action creators as you want
// in any order. Functionality is implied from the name so `doX`
// is an action. `selectX` is a selector.
//
// - action creators are pre-bound to the store.
// - selector names create prop names that sound like the value so
// `selectActiveUsers` here, becomes: `activeUsers`
export default connect(
'doUpdateUser',
'selectActiveUsers',
({ doUpdateUser, activeUsers }) => (
{activeUsers.map(user => (
name: {user.name}
))}
)
)
```
## Features
1. This is not a toy project. This is how I build production Redux apps. It was extracted from real apps where it was used to solve real use cases.
2. It's quite small at [\~9k](https://bundlephobia.com/result?p=redux-bundler). That includes Redux itself, reselect for selectors, as well as an optional super light-weight routing system. If you pair it with [Preact](https://preactjs.com/) and [money-clip](https://github.com/HenrikJoreteg/money-clip) you have a complete PWA toolkit in \~14kb! That's before tree-shaking (could be much less if you don't use everything).
3. Dramatically reduces boilerplate without changing or replacing basic Redux concepts.
4. "Batteries included" approach where you use what you want, and tree-shake out the rest.
5. Simplified and more efficient `connect()` for binding to components (available for [React](https://github.com/HenrikJoreteg/redux-bundler-react) and [Preact](https://github.com/HenrikJoreteg/redux-bundler-preact))
6. Includes a very lightweight, robust, routing system (optional).
7. Supports code-splitting/lazy-loading of Redux bundles.
8. Makes re-use of Redux related code between apps really simple; just publish a bundle to npm.
9. Full [example-app](https://github.com/HenrikJoreteg/redux-bundler-example) available demonstrating data fetching, clientside caching, routing, etc.
10. Can run entirely in a WebWorker using [redux-bundler-worker](https://github.com/HenrikJoreteg/redux-bundler-worker) (complete [example app here](https://github.com/HenrikJoreteg/redux-bundler-worker-example)).
11. Supports the "reactor" pattern letting your react to your application state to dispatch other actions. This lets you write a total "honey badger" of an app that can seamlessly recover from errors and tolerate terrible network conditions.
## Motivation
Redux is awesome, but it's no secret that using it requires writing a fair amount of boilerplate. There are some [tips for reducing it in the official documentation](https://redux.js.org/recipes/ReducingBoilerplate.html) and there's an [open issue with over 100 comments](https://github.com/reactjs/redux/issues/2295) on the redux repo about how to handle it that is left largely unresolved.
I've been building redux apps for quite some time and some of you may have been introduced to it when I first [blogged about it](https://blog.andyet.com/2015/08/06/what-the-flux-lets-redux/) back in 2015. This library is how I build redux apps, I finally decided to open source it.
As I said this isn't a toy project. I'm currently using this library for my app that helps chart anesthesia during surgeries [AnesthesiaCharting.com](https://anesthesiacharting.com). This also builds on some of the ideas that were originally conceived and battle-tested when I was helping Starbucks re-platform and build their [shiny new PWA](https://app.starbucks.com). The point is this is actually how I build things with Redux, and given the lack of "solutions" to the boilerplate issue, I decided to share it.
There's a sample application [the source is here](https://github.com/HenrikJoreteg/redux-bundler-example) which is a good way to see how to build something with it. It's [deployed here](https://redux-bundler.netlify.com/) so you can see how it all works when it's up and running.
Note: redux-bundler includes its dependencies for simplicity to minimize surface area for bugs due to version mismatches. It also exports all the exports from redux. So you can still do stuff like `import { combineReducers } from 'redux-bundler'`. However, this also means you end up with code from redux with the debug blocks `if (process.env.NODE_ENV !== "production")` still present. Build your app with NODE\_ENV="production" before minification to strip that out for production. You can use DefinePlugin for webpack (), loose-envify () for browserify, or rollup-plugin-replace for Rollup () to do this.
## What this enables
This approach of consolidating everything on the store actually enables some interesting things.
* Reuse of redux-related functionality across applications. (For example, I share an "authBundle" between 3 different apps built on the same API).
* You can make configurable bundles! You can write higher-level functions that returns a pre-configured bundle. This is *huge* for reducing boilerplate for things like simple data fetches. See the included `createAsyncResourceBundle` for an example of this.
* Keep things tidy. Behavior is decoupled from display. Components can focus on what they do best: rendering their current props.
* It strongly enforces a set of conventions for building redux apps (this is important for larger teams, especially). For example, you have to name your selectors starting with `select`.
* Supports lazy-loading additional redux bundles even after you've created the store. The new bundles are integrated into the existing redux store. Since, connected components reference things by name instead of directly import functions the the components can be sent in different JS payload than the redux code that will power them because until they're actually used they can reference things that don't yet exist on the store.
* This lib also includes an integrated approach for how to react to certain state conditions in your app. You can define special selectors that start with `react` instead of `select` that will be evaluated on a regular basis and can return actions to trigger in response. This enables really, really interesting patterns of being able to recover from failure and retrying failed requests, etc. The level of reliability that can be achieved here is *very* powerful especially for use in PWAs that may well be offline or have really poor network conditions.
* The fact that you *have to use a selector* to get state from redux dramatically simplifies refactoring of large redux apps and avoids many performance pitfalls.
* You can pass an array of selector names you want to subscribe to and get a callback with changes for those particular selectors. By consolidates state diffing into a single spot in the store, `connect()` doesn't have to do any dirty checking, so the binding code becomes very simple.
* Connected action creators are already pre-bound to the store so you never have to import an action creator and then bind it before using it in your component, which I've found to be really confusing for developers learning redux.
* It includes a debug bundle you can enable to see nice summary of what's happening for each action that is dispatched.
* In debug mode (which is enabled by setting `localStorage.debug` to a truthy value) the store instance is bound to `window` allowing console debugging of all your selectors, action creators via the JS console. For example you can type stuff like `store.selectIsLoggedIn()` to see results or `store.doLogout()` to trigger that action creator even if you don't have UI built for that yet.
* It is uniquely well-suited for running inside a WebWorker. Because so much of your application logic lives in the resulting store, and because it lets you subscribe to changes and get deltas of the state you care about, this whole system is uniquely well suited for being ran off of the main thread. I've put together [an example app that runs entirely in a worker](https://github.com/HenrikJoreteg/redux-bundler-worker-example)
## What about async stuff?!
This is another one of the chief complaints people have with redux. They eventually feel like `redux-thunk` doesn't suit their needs. This generally happens once they need to do something more complex than simple data fetches. Solutions like redux-loop or redux-saga attempt to solve this issue. I've never liked either one or any other solution that I've seen, for that matter. They're generally *way* more complicated than redux-thunk and in my opinion, nearly impossible for beginners to grok.
Let's take a step back. Many developers, if using react will use component life-cycle methods like `componentDidMount` to trigger data fetches required by that component. But this sucks for many reasons:
1. You've coupled data fetching arbitrarily to a component, what if another component needs the same data but it hasn't been fetched yet?
2. What if the component, due to user actions gets removed and immediately added back because the user clicked "back"?
3. What if you know ahead of time that data is *going* to be needed by the application, even if it isn't needed yet?
4. What if it fails and we want to retry a couple of times before we show a "failed" message to the user?
5. What if you want to show the data you already have, while fetching updated data in the background?
The point I'm trying to make is that coupling data fetches to a component being visible, or even to a certain URL in your app isn't ideal.
What you're really trying to do is define a set of *conditions* that should lead to a new data fetch. For example you may want to fetch if:
1. Nothing has actually happened but 5 minutes have passed since the last successful fetch.
2. You don't already have the data
3. It errored last time you fetched and 15 seconds has passed, but you still have some data that you want to keep showing because it's recent enough.
4. You've successfully fetched related data first
5. A user is on any url that includes `/reports` in the pathname.
Good luck writing that with simple procedural code!
Part of the appeal of react, as a movement, was to move toward a more reactive style of programming. Yet, most of our data-related stuff is *very* simplistic.
What we want, is our app to behave like a spreadsheet. I wrote about this in [a post about reactive programming](https://joreteg.com/blog/reactive-programming).
What if we let the current state of the app determine what should happen next? Instead of manually triggering things, what if a certain state could cause an action creator to fire? All of a sudden we can describe the *conditions* under which a data fetch should occur. We don't need better async solutions for redux, thunk is fine, what we need is a way to trigger "reactions" to certain state.
redux-bundler includes a pattern for this. Bundles can include what I call "reactors", which are really just selector functions. They can have dependencies on other selectors, and get passed the entire current state, just like other selectors. But if they return something it gets dispatched. This is all managed by redux-bundler. If your bundle includes a key that starts with `react` it will be assumed to be a reactor. From a reactor you can check for whatever conditions in your app you can dream up and then return the action you want to dispatch. And, to be consistent with the decoupled philosophies, you can return an object containing the name of the action creator you want to trigger and the arguments to call it with.
As an example, I like to make a bundle that just manages all the redirects in my app. Here's an an abbreviated version from an actual app:
```javascript
import { createSelector } from 'redux-bundler'
const publicUrls = ['/', '/login', '/signup']
export default {
name: 'redirects',
reactRedirects: createSelector(
'selectIsLoggedIn',
'selectPathname',
'selectHasNoOrgs',
(isLoggedIn, pathname, hasNoOrgs, activeOrgHasBasicInfo) => {
if (isLoggedIn && publicUrls.includes(pathname)) {
return { actionCreator: 'doUpdateUrl', args: ['/orgs'] }
}
if (!isLoggedIn && pathname.startsWith('/orgs')) {
return { actionCreator: 'doUpdateUrl', args: ['/login'] }
}
if (hasNoOrgs && pathname === '/orgs') {
return { actionCreator: 'doReplaceUrl', args: ['/orgs/create'] }
}
// remove trailing slash
if (pathname !== '/' && pathname.endsWith('/')) {
return { actionCreator: 'doReplaceUrl', args: [pathname.slice(0, -1)] }
}
}
)
}
```
Now I have one unified place to see anything that could cause a redirect in my app.
## What next?
* Learn exactly [what bundles can do](/api-reference/bundle).
* Check out the example app here: to see how to build an app with redux-bundler.
* Learn about all the functionality available in the [included bundles](/api-reference/included-bundles).
* See the [patterns page](/guides/patterns) for tips on how to organize your code, and do things like caching and routing.
## license
[MIT](http://mit.joreteg.com/)
# Patterns
1. *all* redux-related functionality should live in a bundle.
2. Just keep a single, flat folder called `bundles` with one bundle per file.
3. Make an `index.js` file in `bundles` to export the result of `composeBundles()`, the resulting function takes a single argument which is any locally cached or bootstrapped data you may have, and returns a redux store. This is also useful for passing settings or config values to bundles that are dynamic as you see with the `cachingBundle` and `googleAnalytics` below:
> ```javascript
> import { composeBundles, createCacheBundle } from 'redux-bundler'
> import config from '../config'
> import user from '/user'
> import other from './other'
> import googleAnalytics from './analytics'
> import { getConfiguredCache } from 'money-clip'
>
> const cache = getConfiguredCache({
> version: config.browserCacheVersion
> })
>
> export default composeBundles(
> user,
> createCacheBundle(cache.set),
> other,
> googleAnalytics(config.gaId, '/admin')
> )
> ```
4. Data is *always* read from the store via selectors
5. Selectors must be written to take *the entire* state as an argument
6. Selectors must be named starting with the word `select` such as `selectAppTime`.
7. Actions creators must be named starting with the word `do` such as `doLogin`.
## Caching
Persisting data locally can have a huge impact on performance. But comes with many caveats with regard to loading stale data, loading data from another user, and handling changes in "shape" of data that's been cached.
Using [money-clip](https://github.com/HenrikJoreteg/money-clip) with `createCacheBundle` can help address all of these issues. See money-clip readme for more.
This approach is implemented in the [example app](https://github.com/HenrikJoreteg/redux-bundler-example).
## Routing
Use `createRouteBundle()` to generate routes as seen in the example app. When determining what to actually store as the "value" for a given route, I tend to use a component but you could certainly also return a string to be used for `` or any other relevant items.
## React-Native (RN)
If you are using `redux-bundler` with RN make sure you run `global.self = global` as the very first piece of code. The most common approach would be to put the code snippet in a seperate file and import it as the first one in your RN entry point/s.
Some bundles like the `debugBundle` arent compatible with RN. So we cant use `composeBundles()` and only the `composeBundlesRaw()` method can help us out. If you want to use the reactions feature dont forget to compose `createReactionBundle()` in the compose function otherwise your actions returned never got dispatched!
```
import { composeBundlesRaw, createReactorBundle } from 'redux-bundler'
export default composeBundlesRaw(
createReactorBundle(),
// ... add more bundles here
)
```
## Using Redux DevTools
Both the `debug` bundle and redux dev tools are enabled if `localStorage.debug` is set to something "truthy". In this way you can keep your production apps debuggable, you just have to flip that `localStorage.debug` flag to enable it. Also beware that running `localStorage.debug = false` in your browser console won't actually turn it off. This is because LocalStorage serializes everything to strings so the value that's stored is actually the string `"false"` which... is truthy! So to turn it back off again, you can just do: `delete localStorage.debug` instead.
# Top Level API
## `composeBundles(...bundles)`
Returns a function that will return a fully configured store composed of all the bundles **including some built-in ones that you're likely to want**. If you have any data to use as starting state, it can be passed to this function.
Included bundles:
* `appTimeBundle`
* `asyncCountBundle`
* `onlineBundle`
* `createUrlBundle()`
* `createReactorBundle()`
* `debugBundle`
## `composeBundlesRaw(...bundles)`
Same as `composeBundles(...bundles)` but does not include anything bundles by default.
## `createSelector()`
Can be used to create selectors as described in the `selectX` section of the bundle API.
## `HAS_WINDOW`
Is `window` defined
## `IS_BROWSER`
Like `HAS_WINDOW` but also tries to determine if we're in a WebWorker.
## `raf`
Shim for `requestAnimationFrame` with fallback to `setTimeout(0)` for node.
## `ric`
Shim for `requestIdleCallback` with fallback to `setTimeout(0)` for node.
## Exports `*` from redux
As previously stated, this library includes Redux, so redux methods are exported too.
# Bundle API
Things bundles can contain:
## `bundle.name`
The only required attribute your bundle should supply. This will be used as the name of any exported reducer.
## `bundle.reducer` or `bundle.getReducer()`
If you export an item called `reducer` it is assumed it's a ready-to-user redux reducer. Sometimes you need to dynamically configure something like `initialData` in these cases a bundle can supply a `getReducer` function instead that will return a reducer. This can be useful for any setup you may need to do, like defining initialState, or whatnot.
## `bundle.selectX`
Anything you attach that starts with `select` such as `selectUserData` will be assumed to be a selector function that takes the entire state object selects what you want out of it. This supports any function that takes the entire store state and returns the relevant data. If you use the `createSelector` method exported by this library, you can create selectors whose dependencies are string names of other selectors. This allows for loose coupling between modules and means that you never have to worry about creating circular imports when various selectors depend on each other. This is possible because as part of creating the store, the library will resolve all those names into real functions. This is powered by [create-selector](https://github.com/HenrikJoreteg/create-selector) :point\_left: which is basically a fork of reselect.
## `bundle.doX`
Similarly to selectors, if your bundle contains any keys that start with `do`, such as `doSomething` they'll be assumed to be action creators.
These will be bound to dispatch for you and attached to the store. So you can call `store.doSomething('cool')` directly.
**important**: a slightly modified thunk middleware is included by default. So you always have access to `dispatch`, `getState`, and `store` within action creators as follows.
```javascript
const doSomething =
value =>
({ dispatch }) =>
dispatch({ type: 'something', payload: value })
```
Note that unlike standard thunk that uses positional arguments, this passes just one object containing `dispatch`, `getState`, and any other items included by bundles that define `getExtraArgs`.
## `bundle.reactX`
Reactors are like selectors but start with the word `react`. They get run automatically by redux-bundler whatever they return gets dispatched. This could either be an object: `{type: 'INITIATE_LOGIN'}` or it could be a named action creator like: `{actionCreator: 'doInitiateLogin', args: ['username']}`.
This allows a simple, declarative way to ask questions of state, via selectors to trigger an effect via action reators without the need to introduce new approaches to deal with effects.
**important**: It is *easy to make infinite loops*. Make sure that any action triggered by a reactor, immediately change the conditions that caused your reactor function to return something.
## `bundle.getExtraArgs`
If you define this function it should return an object containing items you wish to make available to all action creators of all bundles.
Commonly this would be used for passing things like api wrappers, configs, etc.
**important**: this function will be called *with the store*. This allows you to do things like create API wrappers that automatically handle authorization failures to trigger redirects, etc.
## `bundle.init`
This will be run *once* as a last step before the store is returned. It will be passed the `store` as an argument. This is useful for things like registering event listeners on the window or any other sort of initialization activity.
For example, you may want redux to track current viewport width so that other selectors can change behavior based on viewport size. You could create a `viewport` bundle and register a debounced event listener for the `resize` event on window, and then dispatch a `WINDOW_RESIZED` action with the new width/height and add a `selectIsMobileViewport` selector to make it available to other bundles.
You probably won't need this, but if you return a function from init, that function will be called if you call `store.destroy()`. This can be useful if you're building a micro-frontends or portal system and need to load/unload whole apps in the same webpage.
```javascript
...
init: (store) {
const handleOnline = () => store.dispatch({ type: 'ONLINE' })
window.addEventListener('online', handleOnline)
return () => {
window.removeEventListener('online', handleOnline)
}
}
...
```
## `bundle.persistActions`
If the caching bundle is configured it will look for this property from other bundles. It should contain an array of action types that should cause contents of this bundle's reducer to be persisted to cache. These action types will be used by some generated redux middleware to lazily persist the contents of the reducer any time these actions occur.
Please note this is completely inert if no caching is configured for the app.
# Included Middleware
Redux-bundler includes a few middlewares by default:
## Slightly modified `redux-thunk`
Works like `redux-thunk` except that everything is passed as a single argument and since all our selectors and action creators are attached to the store instance we also pass the store itself, plus anything bundles may have added by using `getExtraArgs`. So it ends up passing something like this as an argument `{dispatch, store, getState, ...extraArgs}` to your thunk function.
This lets you write action creators that don't care about argument position:
```javascript
export const doCoolStuff =
() =>
({ dispatch, myApiWrapper }) => {
dispatch({ type: 'USER_FETCH_STARTED' })
return myApiWrapper('/some-resource')
.then(payload => {
dispatch({ type: 'USER_FETCH_FINISHED', payload })
})
.catch(() => {
dispatch({ type: 'USER_FETCH_FAILED' })
})
}
```
## Debug Middleware
If you're using the `debugBundle` it will also add some logging middleware that logs actions and state with each action and shows you the next reactor that will be dispatched.
## Named Action Middleware
The bundle created by `createReactorBundle` will also inject middleware that allows you to dispatch an object that names the action creator to be used and optionally the arguments to pass to it.
For example dispatching `{actionCreator: 'doLogOut', args: [true]}` would be the same as calling `store.doLogOut(true)`.
This is most useful when writing reactor functions in a bundle where you may not have a direct reference to the action creator function you want to call.
# Included Bundles
We take a "batteries included" approach where you don't have to use any of this stuff but where a pretty complete set of tools required for apps is included out of the box.
## `createDebugBundle([optionsObject])`
This is meant to be leave-in-able in production. It works as follows:
Unless `localStorage.debug` is set to something "truthy" it will do nothing.
It takes the following options (none are required):
* `logSelectors` (default: true): whether or not to log out selectors and their computed value with each action dispatch
* `logState` (default: true): whether to log state after each dispatch
* `logStackTraces` (default: true): whether to log stack traces with each dispatch
* `stackTraceLimit` (default: 100): stack trace limit to set when logging stack traces
* `actionFilter` (default: null): a function to call that determines whether or not to log an action (if debug is enabled). For example, if you want hide the `APP_IDLE` actions pass this: `(action) => action.type !== 'APP_IDLE'`
* `enabled` (default: HAS\_DEBUG\_FLAG): explicitly enable/disable. This is helpful in node.js where there's no localStorage flag.
* `ignoreActions` (default: \[]): an array of actions to ignore when logging.
If enabled:
* The store is bound to `window.store` for easy access to *all selectors and action creators* since they're all bound to the store. This is super helpful for debugging state issues, or running action creators even if you don't have UI built for it yet.
* On boot, it logs out list of all installed bundles
* On each action it logs out:
* action object that was dispatched
* the current state in its entirety
* the result of all selectors after that state change
* if there's a reactor that will be triggered as as result, it will log that out too as `next reaction`
In order to support use inside a Web Worker which doesn't have `localStorage` access debug state is stored in a reducer and it includes `doEnableDebug()` and `doDisableDebug()` action creators. But most people won't need this. Simply use the localStorage flag.
## `createUrlBundle([optionsObject])`
A complete redux-based URL solution. It binds the browser URL to Redux store state and provides a very complete\
set of selectors and action creators to give you full control of browser URLs.
**Handling in-app navigation**: An extremely lightweight in-app navigation approach is to just by rendering normal `` tags, add an `onClick()` handler on your root component and use [internal-nav-helper](https://github.com/HenrikJoreteg/internal-nav-helper) to inspect the events, calling `doUpdateUrl` as necessary. When click events bubble up, it will inspect the event target looking for `` tags and then determining whether or not to consider it an internal link based on its href. See [internal-nav-helper](https://github.com/HenrikJoreteg/internal-nav-helper) library for more details.
Sample root component:
```js
import navHelper from 'internal-nav-helper'
import { connect } from 'redux-bundler-preact'
import { h } from 'preact'
export default connect(
'doUpdateUrl',
'selectRoute',
({ doUpdateUrl, route }) => {
const CurrentPage = route
return (