envoc-strict-context v3.3.3

envoc-strict-context

Overview

This package provides a single utility function, createStrictContext, that enables developers to uniformly create a React Context, Context.Provider, and useContext consumer hook.

The createStrictContext function exposes only the Context Provider and consumer hook, and prevents developers from interacting with the underlying Context directly. Like the React.useState hook, createStrictContext returns an array, rather than an object, so that developers may easily specify appropriate, contextual variable names for the returned Context.Provider and useContext hook.

Usage

const [CounterProvider, useCounterContext] = createStrictContext<CounterState>();

Features

• Prevents Context usage outside of a Provider
• Friendly React Developer Tools Name
• Custom Error Messages

Prevents Context usage outside of a Provider

In most cases, developers intend to consume a Context inside of a matching Provider. Without createStrictContext, if an attempt is made to consume a Context outside of a matching Provider, no error will occur. Instead, the returned value will never update from the default value that was specified when the Context was originally created. This behavior can lead to unanticipated bugs.

// Calling useContext(ThemeContext) outside of ThemeContext.Provider
// will always return 'light', even if that value changes.
const ThemeContext = React.createContext('light');

createStrictContext differs from this behavior by ensuring that a Context is consumed inside of a matching Provider. The useContext hook that is returned from this function will throw an error if it is called outside of its matching Provider.

Friendly React Developer Tools Name

By default, Context Providers will be displayed as Context.Provider in the React Developer Tools Components pane. The createStrictContext function allows developers to specify a name to be used instead. The snippet below will display the Context Provider as Counter.Provider.

const [CounterProvider, useCounterContext] = createStrictContext<CounterState>({
  name: 'Counter'
});

Custom Error Messages

Developers are able to override the default error message by specifying an errorMessage as an argument.

const [CounterProvider, useCounterContext] = createStrictContext<CounterState>({
  name: 'Counter',
  errorMessage: 'This error message will be shown instead of the default'
});

Caveats

When using createStrictContext, developers are unable to specify a default value when the underlying Context is created. The default value for Contexts created using this function will always be undefined.

The returned useContext hook uses the Context value to determine if it is being called inside of its matching Provider. If the Context value is undefined, an error will be thrown.