🍙 useSubstate

Lightweight (<600B minified + gzipped) React Hook to subscribe to a subset of your single app state.

function Component() {
  const [substate, dispatch] = useSubstate(state => {
    return { count: state.count };
  });

  return (
    <div>
      {substate.count}

      <button
        onClick={() => dispatch({ type: "INCREMENT" })}
      >
        Increment
      </button>
    </div>
  );
}

Features

⏬ Lightweight (<600B minified + gzipped)
⚛️ Works with your existing Redux-like store
🙅‍♀️ Avoids unnecessary re-renders
🔂 Uses an external event subscription to short-circuit context propagation (Making it Concurrent React Unsafe)
🎈 Full Flow and TypeScript support coming soon
🎮 You’re in full control of your store and can use it outside React as well

Requirements

⚠️ To use useSubstate, you will need the unstable and experimental React 16.7.0-alpha. Check out the official documentation or this blog post by Dan Abramov for more information.

useSubstate can also be used together with react-redux in your existing Redux application. Check out Comparison To Redux for more information.

Installation

npm install --save use-substate

Usage

You can use useSubstate with your existing Redux store or with a simple alternative (like create-store). This package will export a React Context consumer (SubstateContext) as well the useSubstate hook.

This custom hook will expose an API similar to useReducer. The only argument for useSubstate is a selectSubstate function which is used to select parts of your state to be used within the component that uses the hook. This allows useSubstate to bail out if unnecessary parts change. Every component that uses this custom hook will automatically subscribe to the store.

The example below will show all steps necessary to use useSubstate:

import React, { useState } from "react";
import ReactDOM from "react-dom";

import createStore from "create-store";
import { SubstateProvider, useSubstate } from "use-substate";

const initialState = { count: 0 };
function reducer(state, action) {
  switch (action.type) {
    case "INCREMENT":
      return { count: state.count + 1 };
    case "DECREMENT":
      return { count: state.count - 1 };
  }
}
const store = createStore(reducer, initialState);

function App() {
  const [substate, dispatch] = useSubstate(state => {
    return { count: state.count };
  });

  return (
    <div>
      {substate.count}

      <button onClick={() => dispatch({ type: "INCREMENT" })}>Increment</button>
      <button onClick={() => dispatch({ type: "DECREMENT" })}>Decrement</button>
    </div>
  );
}

ReactDOM.render(
  <SubstateProvider value={store}>
    <App />
  </SubstateProvider>,
  rootElement
);

Comparison To Redux

Redux is a library used to create stores that can be updated via reducers. In fact, useSubstate works flawlessly with your current Redux store.

In opposite to react-redux, this library only requires a selectSubstate function (similar to react-redux's mapStateToProps). It is meant to call the dispatch function with the action directly. Advanced concepts like connectAdvanced or mapDispatchToProps are deliberately not supported.

To use useSubstate with your current react-redux React application, find the react-redux Provider and make sure to wrap it with a SubstateProvider:

import React from "react";
import { render } from "react-dom";
import { Provider } from "react-redux";
+ import { SubstateProvider } from "use-substate";
import { createStore } from "redux";
import todoApp from "./reducers";
import App from "./components/App";

const store = createStore(todoApp);

render(
+ <SubstateProvider value={store}>
    <Provider store={store}>
      <App />
    </Provider>
+ </SubstateProvider>,
  document.getElementById("root")
);

Other Libraries

Besides the open issue in react-redux, there are two other noticeable libraries that solve the a similiar problem:

Acknowledgements

Special thanks to @sophiebits and @gaearon for helping me spot an issue in my initial implementation and showing me how to fix it.

This library is also heavily influenced by the design of useReducer, create-subscription, react-redux, Reducer components in ReasonReact, Elm, Reagent (Clojure), Om (Clojure), and a lot of other libraries that I have seen over the years. Thank you all for pushing the Web forward ❤️.

Contributing

Every help on this project is greatly appreciated. To get you started, here's a quick guide on how to make good and clean pull-requests:

Create a fork of this repository, so you can work on your own environment.

Install development dependencies locally:

git clone git@github.com:<your-github-name>/use-substate.git
cd use-substate
yarn install

Make changes using your favorite editor.
Commit your changes (here is a wonderful guide on how to make amazing git commits).
After a few seconds, a button to create a pull request should be visible inside the Pull requests section.

Future Improvements

Add Flow and TypeScript types. This is actually very important for this library: Actions must be typed as an enum such that the type system can find out if we use the wrong type.
Improve test harness.

License

MIT

philipp-spiess/use-substate