logrock is a React logging library that captures every user action before a critical error occurs and surfaces it as a structured stack — ready to display in a built-in BSOD overlay or send to your error tracking backend.

Table of Contents

• Articles
• Installation
• Quick Start
• Logging
• Reading the Stack
• Custom BSOD
• Properties
• Browser Compatibility
• License

Articles

• ENG: Log Driven Development
• RUS: LogRock: Тестирование через логирование

Installation

# npm
npm install logrock

# yarn
yarn add logrock

Quick Start

Wrap your application in <LoggerContainer>. All logging and error capture happens inside this boundary.

import logger, { LoggerContainer } from 'logrock';

function App() {
  return <main>...</main>;
}

export default function Root() {
  return (
    <LoggerContainer
      sessionID={window.sessionID}
      limit={75}
      getCurrentDate={() => new Date().toISOString()}
      stdout={(level, message, important) => {
        if (important) alert(message);
      }}
      onError={(stackData) => {
        // send the action stack to your backend or error tracker
        sendToServer(stackData);
      }}
      onPrepareStack={(stack) => ({
        ...stack,
        // attach any extra context before the stack is sent
        language: window.navigator.language,
      })}
    >
      <App />
    </LoggerContainer>
  );
}

Logging

Import the logger singleton and call its methods anywhere in your application:

import logger from 'logrock';

logger.log('User opened settings panel');
logger.info('Feature flag "dark-mode" is enabled');
logger.warn('Response time exceeded 2 s');
logger.debug('Computed layout: 1024×768');
logger.error('Failed to parse server response');

Pass true as the second argument to forward the message to the stdout prop of <LoggerContainer>. Use this for messages that should be visible to the user (e.g. a toast or alert):

logger.error('Your session has expired. Please log in again.', true);

Example — logging component state

import { useState } from 'react';
import logger from 'logrock';

export default function Toggle() {
  const [state, setState] = useState<'off' | 'on'>('off');

  function toggle() {
    const next = state === 'off' ? 'on' : 'off';
    logger.info(`Toggle → ${next}`);
    setState(next);
  }

  return <div className={`switch ${state}`} onClick={toggle} />;
}

When a critical error occurs the built-in BSOD overlay displays every recorded action so you can immediately see the sequence of events that led to the crash:

Tip: place log calls around the most complex or error-prone parts of your code so the action trail is meaningful when you need it.

Reading the Stack

Use the useLoggerApi hook inside any component that is a descendant of <LoggerContainer> to access the current stack or trigger an error manually:

import { useLoggerApi } from 'logrock';

function DebugPanel() {
  const { getStackData, triggerError } = useLoggerApi();

  return (
    <button onClick={() => triggerError(getStackData())}>
      Simulate crash
    </button>
  );
}

| Return value | Type | Description | | --- | --- | --- | | getStackData | () => Stack | Returns a snapshot of the current action stack with session metadata | | triggerError | (stack: Stack) => void | Invokes the onError callback manually with the provided stack |

Custom BSOD

Replace the default overlay with your own component by passing it to the bsod prop. Your component receives the same BsodProps as the built-in one:

import { BsodProps, LoggerContainer } from 'logrock';

function MyErrorScreen({ count, stackData, onClose }: BsodProps) {
  return (
    <div className="error-screen">
      <h1>Oops — something went wrong</h1>
      <p>{count} actions recorded</p>
      <button onClick={onClose}>Dismiss</button>
    </div>
  );
}

<LoggerContainer bsod={MyErrorScreen}>
  <App />
</LoggerContainer>

Properties

<LoggerContainer>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | active | boolean | true | Enable or disable logging and event listeners. Disable during tests to keep them isolated. | | bsodActive | boolean | true | Show or hide the BSOD overlay when a critical error occurs. | | bsod | FunctionComponent<BsodProps> | built-in | Custom component to render instead of the default BSOD overlay. | | sessionID | string \| number | — | Associates the session with a backend session ID for correlated error reports. | | limit | number | 25 | Maximum number of actions kept in the stack. Oldest entries are dropped when the limit is exceeded. | | getCurrentDate | () => string | new Date().toLocaleString() | Returns the timestamp recorded in the session metadata. | | onError | (stack: Stack) => void | — | Called when a critical error is captured. Use this to send the stack to your backend or error tracker. | | onPrepareStack | (stack: Stack) => Stack | — | Transform the stack before it is passed to onError. Return the modified stack. | | stdout | (level: string, message: string, important?: boolean) => void | — | Called for every logger.* invocation. When important is true the message was flagged by the caller. |

logger methods

| Method | Description | | --- | --- | | logger.log(msg, important?) | General-purpose log entry | | logger.info(msg, important?) | Informational entry | | logger.warn(msg, important?) | Warning entry | | logger.debug(msg, important?) | Debug entry | | logger.error(msg, important?) | Error entry |

Browser Compatibility

| Browser | Works? | | :------ | :----- | | Chrome | Yes | | Firefox | Yes | | Safari | Yes |

The MIT License

LICENSE