Redux Administrator & Developer Guide

1. Architecture Overview

Redux is a predictable state container for JavaScript applications. At its core, it implements a minimal, framework-agnostic state machine: a single store holds an immutable state tree, plain-object actions describe state transitions, and pure reducer functions compute the next state. The entire public API surface consists of seven functions and two utilities, totaling under 700 lines of TypeScript source.

Redux is not an application framework — it is a coordination primitive. Its value comes from the strict constraints it enforces (immutability, unidirectional data flow, pure reducers) and the ecosystem those constraints enable (time-travel debugging, middleware pipelines, hot reloading, server-side rendering).

The Redux team now recommends Redux Toolkit (@reduxjs/toolkit) as the standard way to write Redux logic. Redux Toolkit wraps this core package with configureStore, createSlice, createAsyncThunk, and other utilities. This guide documents the core redux package internals that Redux Toolkit builds upon.

Architecture Diagram

                        ┌──────────────────────┐
                        │     Application       │
                        │                       │
                        │  dispatch(action) ────┤
                        │                       │
                        │  ◄── subscribe() ─────┤
                        │  ◄── getState() ──────┤
                        └───────────┬───────────┘
                                    │
                        ┌───────────▼───────────┐
                        │        Store          │
                        │                       │
                        │  ┌─────────────────┐  │
                        │  │   Middleware     │  │
                        │  │   Chain          │  │
                        │  │  (applyMiddle-   │  │
                        │  │   ware)          │  │
                        │  └────────┬────────┘  │
                        │           │           │
                        │  ┌────────▼────────┐  │
                        │  │  Root Reducer   │  │
                        │  │  (combine-      │  │
                        │  │   Reducers)     │  │
                        │  └────────┬────────┘  │
                        │           │           │
                        │  ┌────────▼────────┐  │
                        │  │  State Tree     │  │
                        │  │  (immutable)    │  │
                        │  └─────────────────┘  │
                        │                       │
                        │  Listeners (Map)      │
                        └───────────────────────┘

Component Inventory

Technology Stack

Data Flow

1. Application calls store.dispatch(action) with a plain object
2. If middleware is applied, the action passes through the middleware chain (each middleware can inspect, modify, delay, or replace the action)
3. The innermost middleware calls the original store.dispatch, which:
   • Validates the action is a plain object with a string type
   • Calls currentReducer(currentState, action) synchronously
   • Replaces currentState with the return value
   • Iterates all registered listeners (Map-based, snapshot before dispatch)
4. The dispatched action object is returned to the caller

Note

The listener collection uses a Map<number, ListenerCallback> with numeric IDs, not an array. Subscriptions and unsubscriptions during a dispatch take effect on the next dispatch, not the current one — the listener list is snapshotted via shallow copy before iteration.

2. System Requirements

Runtime Requirements

Development Requirements

Build Output Sizes

The library is extremely small. The sideEffects: false flag enables complete tree-shaking for ESM consumers.

3. Configuration Reference

Redux has no configuration files. All configuration is code-level, passed to createStore at instantiation.

createStore Parameters

Important

If preloadedState is omitted and the second argument is a function, Redux treats it as the enhancer. This enables the two-argument form: createStore(reducer, enhancer).

combineReducers Behavior

applyMiddleware Behavior

Environment Variables

Build Configuration

The build is configured via tsup.config.ts:

All builds use sourcemaps. The mangleErrorsTransform Babel plugin replaces verbose error strings with numeric codes (mapped in errors.json) for production builds.

TypeScript Configuration

Three tsconfig files serve different purposes:

Note

The redux path alias in tsconfig.base.json is annotated // @remap-prod-remove-line — it is stripped during production builds so tests can import from the source directly while published types point to the built output.

4. Deployment & Scaling

Publishing

The package is published to npm as redux. The publish lifecycle:

1. prepublishOnly: clean → format check → lint → test
2. prepack: clean → tsup build (4 output formats + types)
3. npm publish uploads dist/ and src/ (per "files" in package.json)

Release Management

Releases use release-it (configured in .release-it.json):

{
  "hooks": {
    "after:bump": "yarn && git add -u"
  },
  "git": {
    "tagName": "v${version}"
  }
}

Git tags follow the v{version} format (e.g., v5.0.1).

Website Deployment

The documentation website deploys to Netlify:

• Build base: website/
• Build command: cd ../docs && yarn && cd ../website && yarn build && cp _redirects ./build
• Publish directory: website/build
• Skip condition: git diff --quiet HEAD^ HEAD -- ../docs/ . (only rebuilds if docs or website changed)
• Node version: 20
• Caching: node_modules/.cache, website/node_modules/.cache, .yarn/.cache

Bundle Size Considerations

Redux is designed to be as small as possible:

• Zero runtime dependencies
• sideEffects: false enables tree-shaking
• Production builds use minified error codes (see errors.json)
• The compose function inlines — if only createStore is imported, compose, bindActionCreators, etc. are tree-shaken away

Tip

The browser-ready ESM build (dist/redux.browser.mjs) is pre-minified with NODE_ENV=production hardcoded. Use it for direct <script type="module"> inclusion without a build step.

5. Operations

Development Workflow

# Install dependencies
yarn

# Run tests (runtime + type-level)
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:cov

# Type-check the type-level tests only
yarn type-tests

# Lint
yarn lint

# Format
yarn format

# Build all outputs
yarn build

# Lint examples
yarn examples:lint

Error Code System

Redux uses a Babel plugin (scripts/mangleErrors.mts) that replaces verbose error strings with numeric codes in production builds. The mapping lives in errors.json:

In production, users see: Minified Redux error #7; visit https://redux.js.org/Errors?code=7 for the full message

Note

The error code system mirrors React's approach. The errors.json file is the source of truth for the mapping between codes and full messages.

Monitoring and Debugging

Redux is designed for observability through Redux DevTools:

• Time-travel debugging: replay actions, jump to any previous state
• Action inspection: view every dispatched action and its payload
• State diff: see what changed between dispatches
• Import/export: save and load state snapshots

Integration via the DevTools Extension Compose:

const composeEnhancers = window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ || compose
const store = createStore(reducer, composeEnhancers(applyMiddleware(thunk)))

Tip

Redux Toolkit's configureStore enables DevTools automatically in development. With the core redux package, you must compose the DevTools enhancer manually.

6. Performance

State Reference Equality

combineReducers returns the same state object reference if no slice reducer returns a new value. This enables efficient change detection in UI libraries:

// Inside combineReducers:
hasChanged = hasChanged || nextStateForKey !== previousStateForKey
// ...
hasChanged = hasChanged || finalReducerKeys.length !== Object.keys(state).length
return hasChanged ? nextState : state

Listener Implementation

Listeners use a Map<number, ListenerCallback> with numeric IDs (auto-incrementing counter). This is more efficient than array-based implementations for frequent subscribe/unsubscribe patterns. The listener map is copy-on-write: ensureCanMutateNextListeners() creates a shallow copy only when needed.

Middleware Chain

The middleware chain is composed once at store creation via compose. Each dispatch passes through the chain with zero additional allocation — middleware functions are pre-composed into a single function reference.

7. Security

Action Validation

Redux enforces strict action validation in the dispatch function:

1. Plain object check: isPlainObject(action) — rejects class instances, arrays, Promises, functions
2. Type existence check: typeof action.type === 'undefined' → error
3. Type string check: typeof action.type !== 'string' → error (new in Redux 5.x)
4. Re-entrancy guard: isDispatching flag prevents dispatch during reducer execution

Serialization Safety

For SSR, Redux state must be serialized to HTML. The recommended pattern escapes < to prevent XSS:

JSON.stringify(preloadedState).replace(/</g, '\\x3c')

Caution

Failing to escape serialized state enables XSS attacks via crafted state values containing </script> tags. Always sanitize when embedding state in HTML.

Supply Chain

• Zero runtime dependencies (the library depends on nothing at runtime)
• All devDependencies are well-known packages from the JS ecosystem
• The sideEffects: false declaration ensures no code runs on import alone

Observable Protocol

The Symbol.observable interop uses a defensive check:

const $$observable = (() =>
  (typeof Symbol === 'function' && Symbol.observable) || '@@observable')()

This falls back to a string key if Symbol.observable is not available, maintaining compatibility without polyfill requirements.

8. Developer Internals

Repository Structure

redux/
├── src/                    # Core library source (TypeScript)
│   ├── index.ts            # Public API barrel export
│   ├── createStore.ts      # Store factory (createStore, legacy_createStore)
│   ├── combineReducers.ts  # Reducer composition
│   ├── applyMiddleware.ts  # Middleware store enhancer
│   ├── bindActionCreators.ts # Action creator dispatch binding
│   ├── compose.ts          # Right-to-left function composition
│   ├── types/              # TypeScript type definitions
│   │   ├── actions.ts      # Action, UnknownAction, AnyAction, ActionCreator
│   │   ├── middleware.ts   # Middleware, MiddlewareAPI
│   │   ├── reducers.ts     # Reducer, ReducersMapObject, derived types
│   │   └── store.ts        # Store, Dispatch, StoreEnhancer, Observable
│   └── utils/              # Internal utilities
│       ├── actionTypes.ts  # @@redux/INIT, REPLACE, PROBE_UNKNOWN_ACTION
│       ├── formatProdErrorMessage.ts  # Minified error codes
│       ├── isAction.ts     # Action type guard
│       ├── isPlainObject.ts # Plain object check
│       ├── kindOf.ts       # Dev-mode type name utility
│       ├── symbol-observable.ts # Symbol.observable polyfill
│       └── warning.ts      # Dev-mode console.error wrapper
├── test/                   # Test suite
│   ├── *.spec.ts           # Runtime tests (one per core module)
│   ├── helpers/            # Test utilities (mock reducers, actions, middleware)
│   ├── utils/              # Tests for utility functions
│   └── typescript/         # Type-level tests (*.test-d.ts)
├── examples/               # 10 example applications
│   ├── async/              # Async data fetching with redux-thunk
│   ├── counter/            # React + RTK counter (JS)
│   ├── counter-ts/         # React + RTK counter (TypeScript)
│   ├── counter-vanilla/    # Vanilla JS counter (no React)
│   ├── real-world/         # GitHub API browser with pagination
│   ├── shopping-cart/      # Shopping cart with optimistic updates
│   ├── todomvc/            # TodoMVC with reselect
│   ├── todos/              # Basic todo list
│   ├── todos-with-undo/    # Todos with redux-undo
│   ├── tree-view/          # Dynamic tree with normalized state
│   └── universal/          # Server-side rendering (Express + React)
├── website/                # Docusaurus documentation site
├── docs/                   # Markdown documentation source
├── scripts/                # Build scripts
│   └── mangleErrors.mts    # Babel plugin for error code extraction
├── errors.json             # Error code → message mapping
├── tsup.config.ts          # Build configuration (4 output formats)
├── tsconfig.base.json      # Shared TypeScript settings
├── tsconfig.build.json     # Build-specific TypeScript config
├── tsconfig.test.json      # Type-test TypeScript config
├── vitest.config.mts       # Test runner configuration
├── package.json            # Package metadata (v5.0.1)
└── netlify.toml            # Website deployment config

Module Reference

createStore.ts — Store Factory

The central module. Creates the store object with getState, dispatch, subscribe, replaceReducer, and [Symbol.observable] methods.

Internal state:

Key behaviors:

• On creation, dispatches { type: '@@redux/INIT{random}' } to populate initial state
• replaceReducer dispatches { type: '@@redux/REPLACE{random}' } to re-initialize
• Random suffixes on internal action types prevent reducers from matching them
• dispatch returns the dispatched action object (middleware may return something else)
• subscribe returns an unsubscribe function; calling it twice is a no-op
• The @@observable method returns a minimal observable that calls observer.next(getState()) on every state change

createStore vs legacy_createStore: Both are exported. createStore carries a @deprecated JSDoc annotation; legacy_createStore is identical in behavior but without the deprecation marker. legacy_createStore delegates to createStore internally.

combineReducers.ts — Reducer Composition

Merges an object of slice reducers into a single root reducer.

Validation (at construction time):

1. Filters out non-function values from the input object
2. Warns (dev only) if any key maps to undefined
3. Calls assertReducerShape — invokes each reducer with:
   • undefined state + @@redux/INIT action → must not return undefined
   • undefined state + @@redux/PROBE_UNKNOWN_ACTION{random} → must not return undefined

Runtime (on each dispatch):

1. Iterates finalReducerKeys, calls each slice reducer with its slice of state + action
2. Checks if any slice returned a new value (reference inequality)
3. Also checks if the number of state keys changed
4. Returns new state object only if something changed; otherwise returns the same reference

Dev-mode warnings:

• Unexpected keys in state that don't match any reducer
• Unexpected state shape (not a plain object)

applyMiddleware.ts — Middleware Enhancer

Returns a StoreEnhancer that intercepts createStore to wrap dispatch.

Composition:

const middlewareAPI: MiddlewareAPI = {
  getState: store.getState,
  dispatch: (action, ...args) => dispatch(action, ...args)
}
const chain = middlewares.map(middleware => middleware(middlewareAPI))
dispatch = compose<typeof dispatch>(...chain)(store.dispatch)

The dispatch reference in middlewareAPI is a closure — it always points to the latest composed dispatch, not the original. This allows middleware to dispatch through the full chain.

Warning

Calling dispatch during middleware construction (before the chain is composed) throws: "Dispatching while constructing your middleware is not allowed." The initial dispatch is a throwing stub that gets replaced once composition completes.

bindActionCreators.ts — Dispatch Binding

Accepts a single action creator or an object of action creators and a dispatch function. Returns wrapped versions that call dispatch(actionCreator(...args)) automatically.

Edge cases:

• Non-function values in the input object are silently skipped
• Passing neither a function nor an object throws with a descriptive error including kindOf() type name
• The bound function preserves this context via .apply(this, args)

compose.ts — Function Composition

Composes functions from right to left. Special cases:

Heavily overloaded in TypeScript (up to 4 functions with full type inference, then rest-args fallback).

src/utils/ — Internal Utilities

Type System Architecture

Redux 5.0.1 exports a comprehensive type system from src/types/:

types/actions.ts

types/store.ts

types/reducers.ts

types/middleware.ts

Code Patterns and Conventions

Formatting (from .prettierrc.json):

Error handling pattern: All public functions validate inputs and throw Error with descriptive messages (dev) or coded messages (prod). The kindOf() utility provides type names in error strings.

Copy-on-write listeners: The listener Map is shallow-copied before mutation via ensureCanMutateNextListeners(). This prevents bugs when subscribers add/remove listeners during notification.

Internal action types use random suffixes:

INIT: `@@redux/INIT${randomString()}`
REPLACE: `@@redux/REPLACE${randomString()}`
PROBE_UNKNOWN_ACTION: () => `@@redux/PROBE_UNKNOWN_ACTION${randomString()}`

This ensures no reducer accidentally handles these internal actions. PROBE_UNKNOWN_ACTION is a function (not a string) because it must generate a unique value on each call during assertReducerShape.

Testing Strategy

Runtime tests (test/*.spec.ts):

Utility tests (test/utils/*.spec.ts):

Type-level tests (test/typescript/*.test-d.ts):

9 type-test files using Vitest's expectTypeOf assertions:

Test helpers (test/helpers/):

Running tests:

yarn test            # Full suite (runtime + typecheck)
yarn test:watch      # Watch mode
yarn test:cov        # With coverage
yarn type-tests      # Type-level tests only (tsc --noEmit)

Example Applications

The examples/ directory contains 10 example apps demonstrating different Redux patterns:

Note

The counter and counter-ts examples use Redux Toolkit (@reduxjs/toolkit), not the core redux package directly. All other examples use core Redux APIs (createStore, combineReducers, applyMiddleware).

Potential Improvements

Based on source analysis and community issues:

1. Documentation consolidation — GitHub issue #4789 discusses merging Redux, RTK, and React-Redux docs into a unified site
2. Outdated tutorial content — Issue #4480 notes tutorials use legacy ReactDOM.render() instead of createRoot(). Issue #4375 reports broken reactions in the Essentials tutorial
3. Reselect docs drift — Issue #4866 flags outdated Reselect references in the selectors guide
4. Next.js guidance — Issue #4713 requests per-route state documentation for Next.js
5. Type improvements — Issue #3455 reports ActionCreator generic losing argument types; issue #4602 reports conflicts between AppThunk and createAsyncThunk.withTypes
6. Normalizr replacement — Issue #4699 notes normalizr is no longer maintained; the docs still reference it

Contributing

Code style:

yarn format         # Auto-format with Prettier
yarn format:check   # Check formatting without modifying
yarn lint           # ESLint

Pre-publish checks: prepublishOnly runs format check, lint, and full test suite.

Git conventions:

• Tags: v{version} (e.g., v5.0.1)
• .git-blame-ignore-revs exists for large formatting commits
• .editorconfig and .prettierrc.json enforce consistent formatting

License: MIT

9. Integration Points

Observable Protocol

Redux stores implement the TC39 Observable proposal via Symbol.observable (or the @@observable string fallback). This enables interop with:

• RxJS: from(store).pipe(...)
• most.js: from(store).map(...)
• Any library implementing the Observable consumer protocol

The observable emits the full state tree on every dispatch via observer.next(getState()).

Store Enhancer Protocol

Store enhancers wrap createStore to add capabilities. The enhancer signature:

type StoreEnhancer = (createStore: StoreCreator) =>
  (reducer: Reducer, preloadedState?: any) => Store

Examples: applyMiddleware, Redux DevTools Extension, persistence enhancers. Enhancers compose via compose:

const enhancer = compose(
  applyMiddleware(thunk, logger),
  devToolsEnhancer,
  persistEnhancer
)

Middleware Protocol

Middleware functions follow a curried three-layer pattern:

type Middleware = (api: { dispatch, getState }) =>
  (next: Dispatch) =>
  (action: Action) => any

• Outer function: receives { dispatch, getState } — called once at store creation
• Middle function: receives next — the next middleware's dispatch (or the store's base dispatch for the last middleware)
• Inner function: receives action — called on every dispatch

React Integration

Via react-redux, Redux integrates with React through:

• <Provider store={store}> — context-based store injection
• useSelector(selector) — subscribe to state slices with reference equality
• useDispatch() — access the store's dispatch function
• connect(mapState, mapDispatch) — HOC-based integration (legacy pattern)