jonbnewman / mobx-store-provider

React Hooks to connect mobx-state-tree to your components

mobx-store-provider

mobx-store-provider is a library that provides React Hooks to setup and access mobx-state-tree models from within React Function Components.

Its goal is to provide a straight-forward, minimalist, and terse API that allows you to easily incorporate mobx-state-tree into functional React components.

1. Installation
2. Basic example
3. API details and examples
   • useProvider - Provide your components with a store
   • useCreateStore - Create a new store inside a component
   • useStore - Use a store in a component
   • getStore - Use a store outside a component
4. Multiple stores
5. Local state
6. Typescript
7. Testing
8. Motivation
9. Upgrading 1.x -> 2.x

---

Installation

npm i mobx-store-provider

yarn add mobx-store-provider

Basic example

The following shows an example application using mobx-store-provider.

App component

At the core of the application we define the main App component.

Inside of the App we use hooks provided by mobx-store-provider to:

1. Create the appStore instance with the useCreateStore hook
2. Retrieve the Provider with the useProvider hook

// App.jsx (Main App component, we use it to create and provide the store)
import React from "react";
import { useProvider, useCreateStore } from "mobx-store-provider";
import AppStore from "./AppStore";
import UserDisplay from "./UserDisplay";

function App() {
  // Create the AppStore instance
  const appStore = useCreateStore(AppStore, { user: "Jonathan" });

  // Get the Provider for the AppStore
  const Provider = useProvider(AppStore);

  // Wrap the application with the Provider passing it the appStore
  return (
    <Provider value={appStore}>
      <UserDisplay />
    </Provider>
  );
}

export default App;

Note that we wrap the application with the Provider, supplying it the appStore as its value.

This makes the appStore available to the rest of the application.

Using the store

In another component somewhere in the application we want to use or gain access to the appStore.

To do this, we use the useStore hook:

// UserDisplay.jsx (A component, we use the store from above inside it)
import React from "react";
import { observer } from "mobx-react";
import { useStore } from "mobx-store-provider";
import AppStore from "./AppStore";

function UserDisplay() {
  // Get access to the store
  const appStore = useStore(AppStore);
  return <div>{appStore.user}</div>;
}

// Wrap it with mobx-react observer(), so updates get rendered
export default observer(UserDisplay);

Note that we also wrap the component with observer() from the mobx-react library.

This is critical, as it ensures the component will render any updates made to the appStore. For more information, see the observer documentation for the mobx-react library.

Defining the store

The code above uses the AppStore mobx-state-tree model. In the context of mobx-store-provider this is referred to as a store.

// AppStore.js (mobx-state-tree store/model)
import { types } from "mobx-state-tree";

const AppStore = types.model({
  user: types.string,
});

export default AppStore;

If you are new to mobx-state-tree, it is recommended you read through the mobx-state-tree documentation.

---

See the full docs

mobx-store-provider's Issues

Be more explicit in multiple stores docs

When I was new to MST I glossed over of the same type (not understanding what it meant) in this:

mobx-store-provider/docs/multiple-stores.md

Line 9 in 34788e0

You may have a need to instantiate multiple stores/models (of the same type) for your particular application. **mobx-store-provider** supports this use case via a unique `identifier` you can pass into the [useProvider](/api/useProvider) and [useStore](/api/useStore) hooks.

Accordingly when I added a new store (definition, not instance) I created a new nested <Provider> (as show on that page). In hindsight I think the RootStore pattern would have been more appropriate, but I wasn't aware of it because that page is titled Multiple stores.

Would you accept a PR to put a ⚠️ on that Multiple stores page that using a single provider and the RootStore approach is better* if you only have one instance of each model type?

* I argue that it's better for this reason.

Suggestion: rename createStore to useCreateStore

When first looking at code using this library, it's hard to guess that createStore is a hook.

I believe following the pattern of prefixing it with use would better describe it.

This change would require a breaking update, but it can be preceded by a deprecation period, updating the docs to favor the new method.

Suggestion: mapStateToProps name is misleading

The mapStateToProps parameter in useStore(identifier, mapStateToProps) is used to map a store to a "view" of it, there are no props on that. I understand the name was taken from redux inject, where it does make sense, but I don't think that's the case in this library

I believe it would be more suitable to call it mapStore or something along that.

Store gets recreated everytime component is re-rendered

When using useCreateStore, the factory method gets called whenever the host component is re-rendered.

I believe this is not the expected behavior, but some code might be relying on this.

This happens because it's called on the hook body:

function useCreateStore(factory: Factory): any {
  return useRef(factory()).current;
}

My suggestion is to replace this call with a memo-d value:

function useCreateStore(factory: Factory, deps: any = []) : any {
  return useMemo(factory, deps);
}

next.js compatibility?

As I see you've taken the lead with functional components and useContext per mobxjs/mobx-state-tree#1363 (comment)

I'd like to use your lib with next.js, wondering if it would work.

The MST example vercel has is from a few years back and uses obsolete patterns (class components and injection) https://github.com/vercel/next.js/tree/canary/examples/with-mobx-state-tree-typescript

Issues with es6 modules in Jest

Thanks for this nice library and the effort spent creating it.

Just to let you know I had issues with ES6 and Jest, it seems your library is not transformed into ES5 when publishing, is that the case or I missing something? So when trying to run a test in Jest (using default create-react-app configuration), I get the following error:

 PASS  src/atoms/Clock/Clock.test.tsx
 FAIL  src/organisms/Header/Header.test.tsx
  ● Test suite failed to run

    /Users/alanrubin/Keytree/Sense/matrix-sense-signage-ui/node_modules/mobx-store-provider/lib/index.js:1
    ({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,global,jest){import useProvider from "./hooks/useProvider";
                                                                                                    ^^^^^^^^^^^

    SyntaxError: Unexpected identifier

      3 | import Clock from 'atoms/Clock'
      4 | import { observer } from 'mobx-react'
    > 5 | import { useStore } from 'mobx-store-provider'
        | ^
      6 | import { IAppStore } from 'models/AppStore'
      7 | import MatrixLogo from './matrix-logo.svg'

That seems to be caused because jest doesn't transpile the node_modules dir - I solved by adding to the package.json a jest configuration to transpile your library in node_modules:

"jest": {
    "transformIgnorePatterns": [
      "node_modules/(?!mobx-store-provider)/"
    ]
  }

But isn't it better to have the library published transpiled?

Thanks,
Alan