@frontity/react-easy-state
Advanced tools
React state management with a minimal API. Made with ES6 Proxies.
NEWS: v6.3.0 fixed a nasty bug that could render zombie children. Please update to this version at least to save yourself some headaches. Thanks!
React Easy State is a practical state management library with two functions and two accompanying rules.
view().store().import React from 'react';
import { store, view } from '@risingstack/react-easy-state';
const counter = store({
num: 0,
increment: () => counter.num++
});
export default view(() => (
<button onClick={counter.increment}>{counter.num}</button>
));
This is enough for it to automatically update your views when needed. It doesn't matter how you structure or mutate your state stores, any syntactically valid code works.
Check this TodoMVC codesandbox or raw code for a more exciting example with nested data, arrays and getter properties.
npm install @risingstack/react-easy-state
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.
store creates a state store from the passed object and returns it. A state store behaves just like the passed object. (To be precise, it is a transparent reactive proxy of the original object.)
import { store } from '@risingstack/react-easy-state';
const user = store({ name: 'Rick' });
// stores behave like normal JS objects
user.name = 'Bob';
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;
store as early as possible.// 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.
this keyword in the methods of your state stores.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.
Wrapping your components with view turns them into reactive views. A reactive view re-renders whenever a piece of store - used inside its render - changes.
import React from 'react';
import { view, store } from '@risingstack/react-easy-state';
// this is a global state store
const user = store({ name: 'Bob' });
// this is re-rendered whenever user.name changes
export default view(() => (
<div>
<input
value={user.name}
onChange={ev => (user.name = ev.target.value)}
/>
<div>Hello {user.name}!</div>
</div>
));
view - including class and function ones - even if they don't seem to directly use a store.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.
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>
));
view implements an optimal shouldComponentUpdate (or memo) for your components.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
batchfunction and built-in batching may be deprecated and removed in the future in favor of React's own batching.
view as the latest (innermost) wrapper when you combine it with other Higher Order Components.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+.
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)} />
));
A singleton global store is perfect for something like the current user, but sometimes having local component states is a better fit. Just create a store inside a function component or as a class component property in these cases.
import React from 'react'
import { view, store } from '@risingstack/react-easy-state'
export default view(() => {
const counter = store({ num: 0 })
const increment = () => counter.num++
return <button={increment}>{counter.num}</button>
})
Local stores in functions rely on React hooks. They require React and React DOM v16.8+ or React Native v0.59+ to work.
useState - in function components, Easy State won't interfere with them. Consider using autoEffect instead of the useEffect hook for the best experience though.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 Counter extends Component {
counter = store({ num: 0 });
increment = () => counter.num++;
render() {
return (
<button onClick={this.increment}>{this.counter.num}</button>
);
}
}
export default view(Counter);
setState in your class components, Easy State won't interfere with it.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);
state. It may conflict with linter rules, which guard against direct state mutations.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() {}
}
getDerivedStateFromProps).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.
Use autoEffect to react with automatic side effect to your store changes. Auto effects should contain end-of-chain logic - like changing the document title or saving data to LocalStorage. view is a special auto effect that does rendering.
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 } })
Global auto effects can be created with autoEffect and cleared up with clearEffect.
import { store, autoEffect, clearEffect } from '@risingstack/react-easy-state';
const app = store({ name: 'My App' })
const effect = autoEffect(() => document.title = app.name)
// this also updates the document title
app.name = 'My Awesome App'
clearEffect(effect)
// this won't update the document title, the effect is cleared
app.name = 'My App'
Use local auto effects in function components instead of the useEffect hook when reactive stores are used inside them. These local effects are automatically cleared when the component unmounts.
import React from 'react'
import { store, view, autoEffect } from '@risingstack/react-easy-state';
export default view(() => {
const app = store({ name: 'My App' })
// no need to clear the effect
autoEffect(() => document.title = app.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])
})
Local effects in class components must be cleared when the component unmounts.
import React, { Component } from 'react'
import { store, view, autoEffect } from '@risingstack/react-easy-state';
class App extends Component {
app = store({ name: 'My App' })
componentDidMount () {
this.effect = autoEffect(() => document.title = this.app.name)
}
componentWillUnmount () {
// local effects in class components must be cleared on unmount
clearEffect(this.effect)
}
}
Creates an observable store from the passed object and returns it. Can be used outside components for global stores and inside components for local stores.
import { store } from '@risingstack/react-easy-state';
const user = store({ name: 'Rick' });
Creates a reactive view from the passed component and returns it. A reactive view re-renders whenever any store data used inside it is mutated.
import React from 'react';
import { view, store } from '@risingstack/react-easy-state';
const user = store({ name: 'Bob' });
export default view(() => (
<div>Hello {user.name}!</div>
));
Immediately executes the passed function and batches all store mutations inside it. Batched mutations are guaranteed to not trigger unnecessary double renders. Most task sources are batched automatically, only use batch if you encounter performance issues.
import React from 'react';
import { view, store } from '@risingstack/react-easy-state';
const user = store({ name: 'Bob' });
function setName() {
batch(() => {
user.name = 'Rick'
user.name = 'Ann'
})
}
Creates a reactive function from the passed one, immediately executes it, and returns it. A reactive function automatically re-reruns whenever any store data used inside it is mutated.
Can be used both outside and inside components.
import { store, autoEffect } from '@risingstack/react-easy-state';
const user = store({ name: 'Bob' })
autoEffect(() => document.title = user.name)
Takes a reactive function (returned by autoEffect) and clears the reactivity from it. Cleared reactive functions will no longer re-rerun on related store mutations. Reactive functions created inside function components are automatically cleared when the component unmounts.
import { store, autoEffect, clearEffect } from '@risingstack/react-easy-state';
const user = store({ name: 'Bob' })
const effect = autoEffect(() => document.title = user.name)
clearEffect(effect)
You can compare Easy State with plain React and other state management libraries with the below benchmarks. It performs a bit better than MobX and similarly to Redux.
This library is based on non polyfillable ES6 Proxies. Because of this, it will never support IE.
Contributions are always welcome, please read our contributing documentation.
Thanks goes to these wonderful people (emoji key):
 Miklos Bertalan 💻 ⚠️ 📖 📝 |  Roland 💻 ⚠️ 📖 |  Daniel Gergely 💻 🎨 💡 |  Peter Czibik 🚇 |
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
React state management with a minimal API. Made with ES6 Proxies.
The npm package @frontity/react-easy-state receives a total of 114 weekly downloads. As such, @frontity/react-easy-state popularity was classified as not popular.
We found that @frontity/react-easy-state demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.