react-easy-state

• Introduction :wave:
• Installation :cd:
• Everyday Usage :sunglasses:
  • Creating global stores
  • Creating reactive views
  • Creating local stores
• Advanced Usage :nerd_face:
  • Adding side effects
• API Summary :book:
  • store(obj)
  • view(Comp)
  • batch(fn)
  • autoEffect(fn)
  • clearEffect(fn)
• Examples with live demos :tv:
• Articles :loudspeaker:
• Performance :rocket:
• Platform support :computer:
• Alternative builds :wrench:
• Contributors :sparkles:

Easy State supports Create React App without additional configuration. Just run the following commands to get started.

npx create-react-app my-app
cd my-app
npm install @risingstack/react-easy-state
npm start

You need npm 5.2+ to use npx.

import { store } from '@risingstack/react-easy-state';

// stores can include any valid JS structure
// including nested data, arrays, Maps, Sets, getters, setters, inheritance, ...
const user = store({
  profile: {
    firstName: 'Bob',
    lastName: 'Smith',
    get name() {
      return `${user.profile.firstName} ${user.profile.lastName}`;
    },
  },
  hobbies: ['programming', 'sports'],
  friends: new Map(),
});

// stores may be mutated in any syntactically valid way
user.profile.firstName = 'Bob';
delete user.profile.lastName;
user.hobbies.push('reading');
user.friends.set('id', otherUser);

import { store } from '@risingstack/react-easy-state';

const userStore = store({
  user: {},
  async fetchUser() {
    userStore.user = await fetch('/user');
  },
});

export default userStore;

userStore.js

import { store } from '@risingstack/react-easy-state';

const userStore = store({
  user: {},
  async fetchUser() {
    userStore.user = await fetch('/user');
  },
});

export default userStore;

recipesStore.js

import { store } from '@risingstack/react-easy-state';
import userStore from './userStore';

const recipesStore = store({
  recipes: [],
  async fetchRecipes() {
    recipesStore.recipes = await fetch(
      `/recipes?user=${userStore.user.id}`,
    );
  },
});

export default recipesStore;

// DON'T DO THIS
const person = { name: 'Bob' };
person.name = 'Ann';

export default store(person);

// DO THIS INSTEAD
const person = store({ name: 'Bob' });
person.name = 'Ann';

export default person;

The first example wouldn't trigger re-renders on the person.name = 'Ann' mutation, because it is targeted at the raw object. Mutating the raw - none store-wrapped object - won't schedule renders.

import { store, view } from '@risingstack/react-easy-state';

const counter = store({
  num: 0,
  increment() {
    // DON'T DO THIS
    this.num++;
    // DO THIS INSTEAD
    counter.num++;
  },
});

export default view(() => (
  <div onClick={counter.increment}>{counter.num}</div>
));

this.num++ won't work, because increment is passed as a callback and loses its this. You should use the direct object reference - counter - instead of this.

Every component that is using a store or part of a store inside its render must be wrapped with view. Sometimes store usage is not so explicit and easy to to miss.

import { view, store } from '@risingstack/react-easy-state';

const appStore = store({
  user: { name: 'Ann' },
});

const App = view(() => (
  <div>
    <h1>My App</h1>
    <Profile user={appStore.user} />
  </div>
));

// DO THIS
const Profile = view(({ user }) => <p>Name: {user.name}</p>);

// DON'T DO THIS
// This won't re-render on appStore.user.name = 'newName' like mutations
const Profile = ({ user }) => <p>Name: {user.name}</p>;

If you are 100% sure that your component is not using any stores you can skip the view wrapper.

import React from 'react';

// you don't have to wrap this component with `view`
export default (() => <p>This is just plain text</p>);

view wrapping is advised even in these cases though.

• It saves you from future headaches as your project grows and you start to use stores inside these components.
• view is pretty much equivalent to memo if you don't use any stores. That is nearly always nice to have.

import React from 'react';
import { view, store } from '@risingstack/react-easy-state';

const user = store({ name: 'Bob' });
const timeline = store({ posts: ['react-easy-state'] });

// this is re-rendered whenever user.name or timeline.posts[0] changes
export default view(() => (
  <div>
    <div>Hello {user.name}!</div>
    <div>Your first post is: {timeline.posts[0]}</div>
  </div>
));

• Using PureComponent or memo will provide no additional performance benefits.

• Defining a custom shouldComponentUpdate may rarely provide performance benefits when you apply some use case specific heuristics inside it.

import React from 'react';
import { view, store } from '@risingstack/react-easy-state';

const user = store({ name: 'Bob', age: 30 });

function mutateUser() {
  user.name = 'Ann';
  user.age = 32;
}

// calling `mutateUser` will only trigger a single re-render of the below component
// even though it mutates the store two times in quick succession
export default view(() => (
  <div onClick={mutateUser}>
    name: {user.name}, age: {user.age}
  </div>
));

If you mutate your stores multiple times synchronously from exotic task sources, multiple renders may rarely happen. If you experience performance issues you can batch changes manually with the batch function. batch(fn) executes the passed function immediately and batches any subsequent re-renders until the function execution finishes.

import React from 'react';
import { view, store, batch } from '@risingstack/react-easy-state';

const user = store({ name: 'Bob', age: 30 });

function mutateUser() {
  // this makes sure the state changes will cause maximum one re-render,
  // no matter where this function is getting invoked from
  batch(() => {
    user.name = 'Ann';
    user.age = 32;
  });
}

export default view(() => (
  <div>
    name: {user.name}, age: {user.age}
  </div>
));

NOTE: The React team plans to improve render batching in the future. The batch function and built-in batching may be deprecated and removed in the future in favor of React's own batching.

import { view } from '@risingstack/react-easy-state';
import { withRouter } from 'react-router-dom';
import { withTheme } from 'styled-components';

const Comp = () => <div>A reactive component</div>;

// DO THIS
withRouter(view(Comp));
withTheme(view(Comp));

// DON'T DO THIS
view(withRouter(Comp));
view(withTheme(Comp));

• If routing is not updated properly, wrap your view(Comp) - with the Routes inside - in withRouter(view(Comp)). This lets react-router know when to update.

• The order of the HOCs matter, always use withRouter(view(Comp)).

This is not necessary if you use React Router 4.4+. You can find more details and some reasoning about this in this react-router docs page.

If you want React Developer Tools to recognize your reactive view components' names, you have to pass either a named function or an anonymous function with name inference to the view wrapper.

import React from 'react';
import { view, store } from '@risingstack/react-easy-state';

const user = store({
  name: 'Rick',
});

const componentName = () => (
  <div>{user.name}</div>
);

export default view(componentName);

Third party helpers - like data grids - may consist of many internal components which can not be wrapped by view, but sometimes you would like them to re-render when the passed data mutates. Traditional React components re-render when their props change by reference, so mutating the passed reactive data won't work in these cases. You can solve this issue by deep cloning the observable data before passing it to the component. This creates a new reference for the consuming component on every store mutation.

import React from 'react';
import { view, store } from '@risingstack/react-easy-state';
import Table from 'rc-table';
import cloneDeep from 'lodash/cloneDeep';

const dataStore = store({
  items: [
    {
      product: 'Car',
      value: 12,
    },
  ],
});

export default view(() => (
  <Table data={cloneDeep(dataStore.items)} />
));

import React from 'react';
import { view, store } from '@risingstack/react-easy-state';

export default view(() => {
  const [name, setName] = useState('Ann');
  const user = store({ age: 30 });
  return (
    <div>
      <input value={name} onChange={ev => setName(ev.target.value)} />
      <input
        value={user.age}
        onChange={ev => (user.age = ev.target.value)}
      />
    </div>
  );
});

import React, { Component } from 'react';
import { view, store } from '@risingstack/react-easy-state';

class Profile extends Component {
  state = { name: 'Ann' };
  user = store({ age: 30 });

  setName = ev => this.setState({ name: ev.target.value });
  setAge = ev => (this.user.age = ev.target.value);

  render() {
    return (
      <div>
        <input value={this.state.name} onChange={this.setName} />
        <input value={this.user.age} onChange={this.setAge} />
      </div>
    );
  }
}

export default view(Profile);

import React, { Component } from 'react';
import { view, store } from '@risingstack/react-easy-state';

class Profile extends Component {
  // DON'T DO THIS
  state = store({});
  // DO THIS
  user = store({});
  render() {}
}

Class components wrapped with view have an extra static deriveStoresFromProps lifecycle method, which works similarly to the vanilla getDerivedStateFromProps.

import React, { Component } from 'react';
import { view, store } from '@risingstack/react-easy-state';

class NameCard extends Component {
  userStore = store({ name: 'Bob' });

  static deriveStoresFromProps(props, userStore) {
    userStore.name = props.name || userStore.name;
  }

  render() {
    return <div>{this.userStore.name}</div>;
  }
}

export default view(NameCard);

Instead of returning an object, you should directly mutate the received stores. If you have multiple local stores on a single component, they are all passed as arguments - in their definition order - after the first props argument.

import { store, autoEffect } from '@risingstack/react-easy-state';

// DON'T DO THIS
const store1 = store({ name: 'Store 1' })
const store2 = store({ name: 'Store 2' })
autoEffect(() => store2.name = store1.name)

// DO THIS INSTEAD
const store1 = store({ name: 'Store 1' })
const store2 = store({ get name () { return store1.name } })

Because of the design of React hooks you have to explicitly pass all none reactive data to a hook-like dependency array. This makes sure that the effect also runs when the none reactive data changes.

import React from 'react'
import { store, view, autoEffect } from '@risingstack/react-easy-state';

export default view(({ greeting }) => {
  const app = store({ name: 'My App' })
  // pass `greeting` in the dependency array because it is not coming from a store
  autoEffect(() => document.title = `${greeting} ${app.name}`, [greeting])
})