reduxjs/redux
github.com/reduxjs/redux ↗ · 331 files · 1.9 MB
Redux Redux is a JS library for predictable and maintainable global state management.
Overview
Redux is a TypeScript implementation of a framework-independent JavaScript state container for application developers: actions enter a synchronous reducer pipeline, and subscribers read the resulting state. This checkout at 56abca4749921d68f40cda20afd2043af9751f72 packages Redux 5.0.1, maintains runtime and type compatibility tests, and hosts a combined documentation website for several Redux libraries. Its distinctive boundaries are a small in-memory core, composable middleware and store enhancers, and separately maintained React examples that illustrate both modern Toolkit usage and older Redux patterns.
System map
The primary deliverable is an npm library whose public boundary is src/index.ts. Store execution, reducer composition, middleware composition, and public types occupy separate modules. Application state lives in a store closure, while React integration belongs to external packages used by examples. The documentation site has its own dependency installation, external source acquisition, and static deployment configuration.
- src/index.ts exports createStore, legacy_createStore, combineReducers, bindActionCreators, applyMiddleware, compose, isAction, isPlainObject, and public store/reducer/action/middleware types.
- createStore owns currentReducer, currentState, listener Maps, a listener ID counter, and the isDispatching guard within each store instance.
- The package exports modern ESM for import consumers, CJS as its default entry, declarations through redux.d.mts, and a legacy ESM module entry; published files include dist and src.
- tsdown builds five output variants: modern ESM, ES2017 legacy ESM, minified production browser ESM, CJS, and declaration-only ESM.
- Root scripts use pnpm, tsdown, Vitest, TypeScript, oxlint, and oxfmt; build cleans generated output and subsequently strips sourcemap file fields.
- Root, docs, and website are independent pnpm projects rather than workspace packages; root settings select hoisted linking, disable automatic peer installation, and allow esbuild dependency builds.
- The counter-ts application creates its store with external @reduxjs/toolkit and renders App inside the external react-redux Provider; these integrations are outside the Redux core implementation.
- Netlify builds the independent docs and website projects, forcibly fetches external docs, runs Docusaurus, and publishes website/build; npm publishing is a separate manual workflow using provenance.
Feature catalog
Redux exposes state-management APIs rather than an application router or hosted backend. Users can create stores, subscribe to changes, compose reducers, bind action creators, customize dispatch, replace reducers, and consume observable state. Teaching applications demonstrate counters, todos, shopping carts, and normalized trees. The website adds multi-library navigation, search, production error explanations, and opt-in live examples.
- Stores expose dispatch, subscribe, getState, replaceReducer, and an observable interoperability method; createStore initializes reducers before returning this interface.
- combineReducers creates a root reducer from function-valued map entries, producing one state slice per accepted key and rejecting undefined slice outputs.
- bindActionCreators accepts a single function or a function map, preserves invocation arguments and this, dispatches each result, and skips non-function map values.
- applyMiddleware customizes dispatch through composable wrappers; compose supports right-to-left composition, an identity function for zero inputs, and unchanged return of a single function.
- The TypeScript counter offers increment, decrement, numeric amount addition, delayed async addition, and conditional addition when the current value satisfies currentValue % 2 === 1.
- The todos example appends and toggles todos and selects all, completed, or active items through its connected visible-list container.
- The shopping-cart example loads mock products, permits additions only when inventory is positive, and clears the cart on checkout request; the tree example supports node counters, child creation, and descendant deletion.
- The site provides navigation and search tabs for Redux, Toolkit, React Redux, and Reselect, renders error messages selected by ?code=N, and starts StackBlitz examples only after user activation on an isolated page.
Data flow
The core input boundary is dispatch, with preloaded state supplying the initial state boundary. Reducers transform state synchronously, and subscribers retrieve the resulting value rather than receiving action or state arguments. Middleware can interpret other input forms before reaching base dispatch. Documentation has a separate pipeline from external source acquisition through code-block checking and static page generation.
- createStore assigns supplied preloaded state to currentState and dispatches INIT before exposing the store, allowing reducers to fill undefined initial state.
- Base dispatch validates a plain-object action and a defined string type before invoking currentReducer; it returns the original action after listener notification.
- combination passes each slice's previous value and the same action to its reducer, builds nextState, and retains the old root object only if references and key counts match.
- Subscription mutations use a copied nextListeners Map, while dispatch iterates its captured listener Map; callbacks receive no arguments and getState returns currentState.
- Middleware receives getState and a forwarding dispatch closure; its chain wraps the base dispatch, so calls to middlewareAPI.dispatch use the completed outer chain.
- The inspected core stores state in memory and accepts preloaded state for hydration; persistence is described as an enhancer capability rather than implemented as serialization or disk writes in createStore.
- Counter input remains a local string until Number(incrementAmount) || 0 converts it; incrementAsync awaits a 500ms mock Promise and feeds its numeric result into the fulfilled reducer.
- External documentation is copied or sparsely cloned into website/external; TypeScript code blocks become virtual files, receive checker diagnostics, and are syntactically emitted through oxc for JavaScript presentation.
Behavior traces
The traced flows cover core startup, browser interaction, middleware construction, async counter behavior, reducer replacement, observable delivery, checkout, and documentation acquisition. These walkthroughs follow source execution order and preserve the important conditional branches. They describe expected behavior from code inspection, without asserting successful runtime execution.
- Core startup: createStore validates reducer → normalizes an enhancer passed as argument two → delegates through enhancer(createStore) when supplied; otherwise it allocates state/listeners → dispatches INIT → returns the store.
- Vanilla counter: module import → createStore(counter) → render → subscribe(render); an increment click dispatches INCREMENT → counter returns state + 1 → dispatch invokes render → getState().toString() updates the DOM.
- Middleware setup: applyMiddleware(...)(createStore) creates the base store → installs a throwing temporary dispatch → calls each middleware with middlewareAPI → composes wrappers around store.dispatch → returns the copied store with enhanced dispatch.
- Toolkit counter: index.tsx renders Provider(store) and App → App renders Counter → Add Async dispatches incrementAsync(amount) → pending sets loading → fetchCount resolves after 500ms → fulfilled sets idle and adds the payload; rejected sets failed.
- Reducer replacement: replaceReducer validates nextReducer → assigns currentReducer → dispatches REPLACE; combination reuses existing slices, initializes newly undefined slices, and drops keys absent from its new reducer map.
- Observable subscription: store's observable method returns a subscribable object → subscribe validates observer → observeState immediately calls next(getState()) when next exists → registers observeState through store.subscribe → returns its unsubscribe handle.
- Checkout: checkout(products) snapshots getState().cart → dispatches CHECKOUT_REQUEST, resetting cart → shop.buyProducts invokes its timed callback → CHECKOUT_SUCCESS is dispatched with the saved cart; rollback is an explicitly commented alternative CHECKOUT_FAILURE path.
- Docs acquisition: parse flags and requested library names → reject unknown names → skip existing targets unless forced or locally sourced → copyLocalSource or cloneSource → optionally watch local files and spawn pnpm start; clone failures remove partial targets and retry once.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is established here. Root Vitest tests exercise runtime contracts, while TypeScript fixtures exercise API inference and extension types. CI describes source tests, packed-artifact tests, a compiler-version matrix, and consumer integration builds. This is a bounded inspection, and test discovery and direct source imports limit what can be inferred about examples, documentation, and distribution coverage.
- Root test uses vitest --run --typecheck, with globals enabled and discovery rooted at test; type-tests separately invokes tsc against test/typescript. These configurations were inspected without execution.
- createStore tests assert unsubscribe behavior during notification, subscriptions added mid-dispatch, and the latest subscription snapshot for nested dispatch.
- Store tests cover plain-object validation, forbidden reducer-time store operations, recovery after a reducer exception, and non-string action type rejection, including acceptance of an empty string type.
- combineReducers tests exercise invalid map entries, undefined outputs, initialization failure, referential equality, and root shape changes when reducers are added, changed, or removed.
- Middleware tests cover construction-time dispatch rejection, one-time setup, recursive dispatch through the chain, thunk behavior, and extra dispatch arguments; observable tests include unsubscribe and RxJS integration.
- Declaration fixtures use expectTypeOf and typed middleware examples for Promise dispatch, thunk dispatch, exact state access, and custom action unions; CI specifies TypeScript 5.6 through 7.0 plus a non-blocking next compiler.
- CI describes lint, format, source tests, build/pack, TEST_DIST artifact tests, package-type analysis, and pinned Toolkit consumer projects for Next, Vite, Node, React Native, and Expo; some tests such as compose.spec.ts import source directly despite TEST_DIST.
- The inspected counter-ts reducer suite asserts initialization and three synchronous actions, without async lifecycle assertions in that file; examples use separate react-scripts test commands and fall outside the root Vitest test directory.
Risk map
These are source observations and explicitly marked hypotheses, not confirmed vulnerabilities. The inspected core executes caller-provided reducers and middleware in process and validates only a limited action shape. Operational boundaries appear in documentation acquisition, mutable build output, browser embeds, and publishing automation. Compatibility and validation gaps require attention because the library has several distributed formats and the site consumes independently changing repositories.
- Base dispatch validates action shape and type but performs no payload authorization, sanitization, or deep serializability validation in the inspected implementation; payload and reducer trust remain application responsibilities.
- getState returns the stored reference, and combination detects changes using slice references rather than deep comparisons; a mutating reducer can violate the documented pure-reducer contract without this mechanism detecting the mutation. (inferred)
- Subscriber callbacks run after currentState is assigned and have no individual exception handling; a throwing callback stops ordinary Map.forEach iteration and does not roll back the already assigned state.
- The main CI path filter lists src, test, .github, tsdown.config.mts, and pnpm-lock.yaml, but omits package.json, scripts, tsconfig files, and vitest.config.mts; an isolated change to an omitted file does not satisfy the build job's src condition.
- External docs default to master refs, honor caller-provided repository/ref/local-source settings, and copy or symlink files from outside the checkout; --force and local refresh remove existing generated targets before reacquisition.
- Netlify sets DOCS_TYPECHECK=warn, and the code-block plugin then emits warnings rather than failing on diagnostics; this configuration permits publication with reported snippet type errors.
- Build is a mutating operation: clean removes dist and coverage, the Babel plugin may rewrite tracked errors.json, and transform failures are logged before returning null rather than explicitly rethrown by the tsdown hook.
- The vanilla example loads an unpinned redux@latest browser module from unpkg, while legacy examples declare Redux 4 and React 17; these examples therefore do not uniformly exercise the pinned Redux 5 source.
Extension points
Core extensibility comes from function interfaces rather than a named plugin registry. Reducers define state transitions, middleware wraps dispatch, and enhancers wrap store creation. Runtime reducer replacement and observable interoperability expose additional integration seams. Website extensibility uses explicit library metadata, Docusaurus plugin instances, navbar component registration, and configurable Markdown transformation hooks.
- A custom root reducer plugs directly into createStore; the Reducer type separates returned state, accepted actions, and optional preloaded-state input shape.
- Reducer maps plug into combineReducers, whose mapped types infer combined state, action unions, and partial preloaded state; only function-valued entries participate at runtime.
- Middleware plugins implement api => next => action with unknown action inputs and outputs; applyMiddleware overloads accumulate middleware dispatch extensions into the enhanced store type.
- StoreEnhancer wraps a StoreEnhancerStoreCreator and combines store/state extensions; createStore delegates to the enhancer before allocating its own base store.
- replaceReducer supports dynamic reducer loading and hot replacement, while the observable method provides reactive-library integration using Symbol.observable or the @@observable fallback.
- Adding an external documentation library involves the sources acquisition table, libraries navigation metadata, and a Docusaurus docs-plugin instance; these are separate explicit configuration seams.
- Navbar ComponentTypes registers custom-libraryDropdown and custom-libraryLinks; useCurrentLibrary chooses a non-root route prefix match, then root metadata, then the first library.
- transpileCodeblocks accepts custom compiler settings, TypeScript/JavaScript post-processors, replacement-node assembly, and file extensions; code-block metadata can explicitly opt out with no-transpile.
Contributor handoff
Start with the public export surface and the implementation/type pair for the affected API. Preserve synchronous reduction, subscriber snapshot behavior, and package-format compatibility when editing the core. Tests and CI were inspected, not executed, and this bounded report does not establish exhaustive coverage or passing checks. Website acquisition and root build commands have side effects, so future execution requires authority beyond this read-only investigation.
- For a core change, first read src/index.ts, the affected implementation, and matching public types; these jointly define exported names, runtime behavior, and consumer contracts.
- Subscription changes must preserve copy-on-write Maps, idempotent unsubscribe, and nested-dispatch snapshots; read the corresponding createStore tests before changing listener bookkeeping.
- Do not handle randomized Redux INIT, REPLACE, or probe strings as application action types; reducers must initialize undefined state and return current state for unknown actions.
- createStore's deprecation annotation recommends external Toolkit configureStore while explicitly retaining the core API; legacy_createStore is the documented alternative without the visual deprecation warning.
- When execution is authorized, use the existing pnpm test, pnpm type-tests, pnpm lint, and pnpm format:check scripts and scope the first runtime check to the affected suite; tests and CI in this report were inspected, not executed.
- Packaging changes require reviewing exports, all tsdown output variants, TEST_DIST aliasing, and CI's packed-artifact checks; source-direct imports can bypass artifact resolution even in the dist job.
- Keep project installation boundaries distinct: root/docs/website are independent pnpm projects, and standalone examples have their own manifests; older examples' Redux 4 dependencies are not proof of Redux 5 compatibility.
- Before website execution, inspect fetch-external-docs and Netlify settings for clone/copy/removal behavior, moving external refs, warning-only snippet checks, and required isolation headers; publishing also has separate manual npm and automatic commit-preview workflows.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 112 | docs/config |
| TypeScript | 71 | 53% |
| JavaScript | 62 | 46% |
| JSON | 22 | docs/config |
| CSS | 11 | docs/config |
| YAML | 11 | docs/config |
| HTML | 6 | docs/config |
| TOML | 1 | 1% |
Start reading here
Probable source entrypoint: src/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (17 files)
Source layout — src/
| Path | Files |
|---|---|
src/types/ | 1 |
src/applyMiddleware.ts | 1 |
src/createStore.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
examples/ | 106 |
docs/ | 90 |
website/ | 50 |
test/ | 22 |
src/ | 17 |
.github/ | 15 |
scripts/ | 3 |
logo/ | 2 |
Docs found: CONTRIBUTING.mdLICENSE.mdREADME.mddocs/FAQ.mddocs/api/Store.mddocs/api/api-reference.mddocs/api/applyMiddleware.mddocs/api/bindActionCreators.mddocs/api/combineReducers.mddocs/api/compose.md
Package
package.json — redux v5.0.1, 17 declared dependencies.
@arethetypeswrong/cli@babel/core@types/babel__core@types/babel__helper-module-imports@types/nodecross-envglobnetlify-plugin-cacheoxfmtoxlintpkg-pr-newrxjs
CI & config entrypoints
README.md— Repository readmesrc/index.ts— TS entrypointexamples/counter-ts/src/App.tsx— React root.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/release-commit.yml— GitHub Actions workflowpackage.json— npm scripts: build, clean, format, format:check, lint, lint:fix, prepack, prepublishOnlywebsite/package.json— npm scripts: build, deploy, dev, fetch-docs, start, swizzleexamples/counter-ts/package.json— npm scripts: build, eject, start, testexamples/counter-vanilla/package.json— npm scripts: build, startexamples/counter/package.json— npm scripts: build, eject, start, test
Structural health signals
Average score 9.5/10 across 96 analyzed source files; 1 hotspot surfaced.
website/docusaurus.config.ts— 462 lines, score 5.5 (Large file, Deep nesting)website/plugins/remark-typescript-tools/transpileCodeblocks/plugin.ts— 419 lines, score 6.9 (Deep nesting, High churn)website/plugins/remark-typescript-tools/transpileCodeblocks/compiler.ts— 230 lines, score 7.4 (Deep nesting, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
56abca4749922026-09-29 — Merge pull request #4960 from reduxjs/ci/release-commit-skip-forksab15e57825ca2026-09-29 — Skip Release Commit workflow in forks2c54225d63152026-09-28 — Merge pull request #4958 from reduxjs/docs/fundamentals-stackblitzb0f9ea4bfa512026-09-28 — Point Fundamentals embeds at the flipped example repo tags2532800831162026-09-28 — Rewrite Fundamentals tutorial with modern example setup