React-use-logs NPM

react-use-logs

⚛️ 🖨️ A hierarchy sensitive, middleware-defined console.log for React and React Native. ✨

🔥 Features

🔋 Batteries included.
🦄 Declare custom log types.
👪 Supports JSX-scoped filtering and functionality.

🚀 Getting Started

yarn add react-use-logs

✏️ Usage

👶 2.1 Basic Example

By default, react-use-logs exports a useLogs() hook, which works pretty much just like your standard window.console object:

import { useLogs } from "react-use-logs";

export default () => {
  const logs = useLogs();
  return <div onPress={() => logs.debug("Normal", "Old", { console: true })} />
};

🏹 2.2 Middleware

It's possible to define custom handlers for particular calls to useLogs(). First, wrap your application in a <LogsProvider />:

import React from 'react';
import LogsProvider from 'react-use-logs';

export default () => (
  <LogsProvider>
    {/* TODO: awesome app here */}
  </LogsProvider>
);

Once this is done, you can pass a custom middleware prop, which is an array that accepts Middleware functions which take the following form:

function someMiddleware(level: string, messages: unknown[], next: () => void) {
  // Do something with the message.
  alert(...messages);
  // Allow the next middleware in the chain to execute:
  next();
}

Next, you can use the middleware as follows:

import React from 'react';
import LogsProvider from 'react-use-logs';

import { someMiddleware, someOtherMiddleware } from './middleware';

export default () => (
  <LogsProvider middleware={[someMiddleware, someOtherMiddleware]}>
    {/* TODO: awesome app here */}
  </LogsProvider>
);

At this point any call to logs.debug, for example, will instead get passed through the middleware chain.

Notice: By default, a LogsProvider will use the default builtin logging mechanism, the LogLevel middleware. This is based on loglevel. However, if you override the middleware prop for a root-level LogsProvider, this will not be included by default. You can reintroduce the standard console behaviour by including the LogLevel middleware exported by the library.

👪 2.2.1 Nested Middleware

It's also possible to declare specific middleware for different parts of the DOM tree. This is achieved by nesting a child LogsProvider, and declaring an additional middleware prop. The middleware supplied here will be appended to the global middleware.

import React from 'react';
import LogsProvider, { LogLevel } from 'react-use-logs';

import { someMiddleware, someOtherMiddleware } from './middleware';

export default () => (
  <LogsProvider middleware={[LogLevel, someMiddleware]}>
    <LogsProvider middleware={[someOtherMiddleware]}>
      {/* TODO: some special logging route here */}
    </LogsProvider>
    {/* TODO: awesome app here */}
  </LogsProvider>
);

🦄 2.3 Custom Types

By default, react-use-logs uses the existing window.console export format, i.e:

import { useLogs } from "react-use-logs";

const logs = useLogs();
logs.trace("");
logs.debug("");
logs.info("");
logs.warn("");
logs.error("");

By using a custom LogsProvider, you can specify an additional levels prop to declare custom log levels:

import React from 'react';
import LogsProvider from 'react-use-logs';

export default () => (
  <LogsProvider levels={["good", "bad", "ugly"]}>
    {/* TODO: awesome app here */}
  </LogsProvider>
);

This will result in useLogs returning an object like so:

import { useLogs } from "react-use-logs";

const logs = useLogs();
logs.good("");
logs.bad("");
logs.ugly("");

Notice Similar to middleware, for a root-level LogsProvider a defined levels prop will override the original default levels. For nested providers, the contents of the levels will be appended to the inherited ones.

2.4 🤫 Filtering Logs

You can specify a level prop to a LogsProvider to declare the minimum actionable level, which obeys prioritized order. In the example below, it is only possible for warn and error events to be executed; all other invocations will be ignored.

import React from 'react';
import LogsProvider from 'react-use-logs';

export default () => (
  <LogsProvider level="warn">
    {/* TODO: silent app here */}
  </LogsProvider>
);

In addition, you can disable logging altogether for any child component by passing a disabled prop:

import React from 'react';
import LogsProvider from 'react-use-logs';

export default () => (
  <LogsProvider disabled>
    {/* TODO: silent app here */}
  </LogsProvider>
);

💢 2.4.1 Strict Mode

By default, LogsProviders operate in Strict Mode. This has the following effect:

A disabled LogsProvider will disable logging for all children in the tree.
The selected level of the LogsProvider will serve as the minimum log level for nested children.

Although deterministic, this is not useful for debugging. This is because it is sometimes useful to temporarily activate logging for select portion of a silenced log tree. To enable nested LogProviders to ignore a parent's configuration, you can disable strict mode by passing a strict={false} prop:

<>
  <Logs disabled strict={false}>
    {/* because the parent is not strict, we can enable the child tree */}
    <Logs disabled={false}>
    </Logs>
  </Logs>
  <Logs level="warn" strict={false}>
    {/* because the parent is not strict, we can log more granular information */}
    <Logs level="trace">
    </Logs>
  </Logs>
</>