This library is designed to reduce the boilerplate of interacting with an api, normalizing and caching responses, and describing api states.

Usage no npm install needed!

<script type="module">
  import churchcommunitybuilderReduxModules from 'https://cdn.skypack.dev/@churchcommunitybuilder/redux-modules';


Redux Modules

This library is designed to reduce the boilerplate of interacting with an api, normalizing and caching responses, and describing api states.


yarn add @churchcommunitybuilder/redux-modules


There are 3 main assumptions of this library

  1. You are using React
  2. You are using Redux
  3. You are using Redux Thunk with an extra argument that interacts with an api

You'll first need to make sure that your root reducers composes the two reducers exported from this library.

import { moduleReducers } from '@churchcommunitybuilder/redux-modules'

const appReducer = combineReducers({

Next, make a moduleFactory that encapsulates how to pass requests to your thunk api arg.

import { getModuleFactory } from '@churchcommunitybuilder/redux-modules'

export const moduleFactory = getModuleFactory((request, api) =>

where api is you thunk arg and request is defined as

interface RequestConfig {
  url: string
  method?: 'get' | 'post' | 'put' | 'delete'
  params?: {}
  data?: {}
  headers?: {}

At this point, everything should be wired up and you can begin creating modules.

inteface Entity {
  id: number

const module = moduleFactory.create<Entity>()(
    get: moduleFactory.get<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    getList: moduleFactory.getList<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    put: moduleFactory.put<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    post: moduleFactory.post<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    delete: moduleFactory.delete<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,



This is used to create the module and pull together the normalizr schema and the api definitions. Returns the schema, entity selectors, and the api definitions


A thin wrapper around creating a normalizr schema


All api definition factories share a similar signature:

  1. A function taking the api params and returning a request config object.
  2. An optional unique identifier for the module (since the url/http method is by default the unique id)

Each api definition has the following values:

  • api: The api action creator that was passed in
  • execute: A thunk that sets pending statuses, calls the api, and merges the response into redux state
  • metaSelector: A selector to get the metadata about the module (i.e. current api status, item ids, paging)
  • getKey: A helper to get the module's unique key


This api definition has all of the above, with the addition of a useModule hook that returns the entity and metadata for a module


This api definition also has useModule, and additionally has an itemsSelector which will get the entities for the module


This library exports two test helpers from @churchcommunitybuilder/redux-modules/testing.


This can be used to mock modules and entities in your redux store. actions is an array that should be dispatched to your store

import { getModuleMock } from '@churchcommunitybuilder/redux-modules/testing'

export const moduleMock = getModuleMock<Entity>(

const entity = moduleMockEntities(1)
const entities = moduleMockEntities(10)
const entity = moduleMockEntities({ id: 1 })
const entities = moduleMockEntities([{ id: 1 }, { id: 2 }])

const { entity, actions} = moduleMock.mockModule(1, 'uniqueModuleKey') // creates entity, and updates the module's metadata
const { entity, actions} = moduleMock.mockModule(1) // creates one default module
const { entities, actions} = moduleMock.mockModule(10) // creates ten default module
const { entity, actions} = moduleMock.mockModule({ id: 1 }) // creates one entity merged with the default entity
const { entities, actions} = moduleMock.mockModule([{ id: 1 }, { id: 1 }]) // creates two entity merged with the default entity


Used to mock a modules metadata

const meta = mockMeta({ status: ApiStatus.Pending })