Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createRavenMiddleware
✓ import createRavenMiddleware from 'raven-for-redux';
✗ import { createRavenMiddleware } from 'raven-for-redux';
The main middleware factory function is a default export in JavaScript. TypeScript users should use `import * as createRavenMiddleware`.
createRavenMiddleware (TypeScript)
✓ import * as createRavenMiddleware from 'raven-for-redux';
✗ import createRavenMiddleware from 'raven-for-redux';
For TypeScript projects utilizing DefinitelyTyped typings, the 'import * as' syntax is required for correct type inference due to the way the module is structured.
Raven
✓ import Raven from 'raven-js';
✗ const Raven = require('raven-js');
The Raven object from the 'raven-js' package is a direct dependency of the middleware. `raven-js` is a legacy Sentry client and is largely CommonJS-style, but also supports ESM imports in modern bundlers.
This example demonstrates how to integrate `raven-for-redux` with a Redux store, capturing actions as Sentry breadcrumbs and attaching state context to errors. It includes a mock reducer, Raven initialization, and an example of error capturing with custom options.
import Raven from "raven-js";
import { createStore, applyMiddleware, combineReducers } from "redux";
import createRavenMiddleware from "raven-for-redux";
// Mock reducer for demonstration
const initialState = { count: 0, user: { id: 1, name: 'Guest' } };
function reducer(state = initialState, action) {
switch (action.type) {
case 'INCREMENT':
return { ...state, count: state.count + 1 };
case 'LOGIN':
return { ...state, user: action.payload };
default:
return state;
}
}
// Initialize Raven (or mock it for local development without a DSN)
const SENTRY_DSN = process.env.SENTRY_DSN ?? "https://examplePublicKey@o0.ingest.sentry.io/0";
// In a real application, you would always provide a valid DSN.
Raven.config(SENTRY_DSN).install();
const store = createStore(
reducer,
applyMiddleware(
// Middlewares that intercept or emit actions should generally precede raven-for-redux.
createRavenMiddleware(Raven, {
breadcrumbMessageFromAction: action => action.type,
breadcrumbDataFromAction: action => ({ actionPayload: action.payload }),
stateContext: state => ({ user: state.user }),
actionFilter: action => action.type !== 'IGNORE_THIS_ACTION'
})
)
);
// Dispatch some actions to generate breadcrumbs
store.dispatch({ type: 'INCREMENT' });
store.dispatch({ type: 'LOGIN', payload: { id: 123, name: 'Alice' } });
store.dispatch({ type: 'INCREMENT' });
store.dispatch({ type: 'IGNORE_THIS_ACTION' }); // This action will be filtered out
// Simulate an error to capture state and breadcrumbs
try {
throw new Error("Simulated error during user interaction!");
} catch (e) {
Raven.captureException(e);
}
console.log('Final State:', store.getState());
// In a real app, console.logs would typically be replaced by actual Sentry reports.
Debug
Known issues
breakingThe underlying Sentry client, `raven-js`, is officially deprecated by Sentry. New projects should migrate to `@sentry/browser` and `@sentry/redux` for modern Sentry integration.fixConsider migrating your Sentry integration to the `@sentry/browser` and `@sentry/redux` packages for continued support and new features. This package will not work with modern Sentry SDKs.
affects: >=1.0.0
gotchaA specific bug exists in `raven-js` version 3.14.0 that can be triggered by `raven-for-redux`, potentially preventing breadcrumbs or errors from being reported correctly.fixAvoid using `raven-js` version 3.14.0. Downgrade to an earlier 3.x version or upgrade to a later version if available and compatible. The best long-term solution is to migrate to `@sentry/browser`.
affects: =3.14.0 (for raven-js)
gotcha`raven-for-redux` middleware should be placed *after* other Redux middlewares (like `redux-thunk` or `redux-promise`) that might intercept, transform, or emit new actions. Incorrect placement can lead to actions not being logged or incorrect state being attached.fixEnsure `createRavenMiddleware` is the last middleware applied in your `applyMiddleware` chain if other middlewares modify or generate actions.
affects: >=1.0.0
gotchaThe `breadcrumbDataFromAction` option, while powerful, should be used with caution. Logging large or sensitive portions of the action object or state can negatively impact performance and Sentry event size limits.fixBe selective about the data returned by `breadcrumbDataFromAction`, including only necessary, non-sensitive, and small pieces of information to avoid performance issues and Sentry data caps.
affects: >=1.0.0
gotchaWhen using TypeScript with `raven-for-redux`'s DefinitelyTyped bindings, the import style for `createRavenMiddleware` differs from typical ES module default imports.fixUse `import * as createRavenMiddleware from 'raven-for-redux';` instead of `import createRavenMiddleware from 'raven-for-redux';` in TypeScript files to correctly utilize the provided typings.
affects: >=1.0.0 (with TypeScript)
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'config') at createRavenMiddleware
The `Raven` object was not correctly initialized or passed as the first argument to `createRavenMiddleware`.
fixEnsure `Raven.config('<YOUR_DSN>').install();` is called and completes successfully before creating the middleware, and that the initialized `Raven` object is passed as the first argument to `createRavenMiddleware`. Sentry: Breadcrumbs or errors are not being reported, or are malformed in Sentry dashboard.
This symptom commonly occurs if `raven-js` version 3.14.0 is being used, which has a known bug impacting `raven-for-redux`.
fixDowngrade your `raven-js` dependency to a version other than 3.14.0, or preferably, migrate your Sentry integration to the actively maintained `@sentry/browser` package.
Actions appear in Sentry breadcrumbs without expected modifications from other middlewares, or the attached state context is incorrect/stale.
The `raven-for-redux` middleware is likely placed too early in the Redux `applyMiddleware` chain, causing it to capture state or actions before other middlewares have processed them.
fixReorder your middlewares so that `createRavenMiddleware` is placed after any other middlewares that modify actions or state (e.g., `redux-thunk`, `redux-promise`, `redux-saga`).
Audit
Dependencies
reduxrequiredRequired as a peer dependency for Redux store integration and middleware application.
raven-jsrequiredThe core Sentry JavaScript client library that this middleware integrates with. Note that raven-js itself is deprecated by Sentry.