Temper ·
Table of contents
Getting Started
This readme is meant to get you familiar with the Temper way of doing things. If you're looking for something specific, please visit the documentation site. If you're just starting out with Temper, read on!
For the purpose of this guide, we'll create a simple counter that prints You've reached the target! when you get to the value of 5.
Create React App
Temper is a state management library for React, so you need to have React installed and running to use Temper. The easiest and recommended way for bootstrapping a React application is to use Create React App:
npx create-react-app my-app
npx is a package runner tool that comes with npm 5.2+ and higher, see instructions for older npm versions.
For more ways to install Create React App, see the official documentation.
Installation
Using npm:
npm install temperjs
Using yarn:
yarn add temperjs
withTemper
If you want to use Temper states, you need to wrap your component (preferably the root component) with the hoc withTemper
.
import React from 'react';
import { withTemper } from 'temperjs';
function App() {
return <Counter />
}
export default withTemper(App);
We'll implement the Counter
component in the following section.
Traits
Temper states are called Traits. Traits are globally shared units of state that components can subscribe to. Traits can be read and written from any component in the application tree. Subscribed components will rerender everytime the Trait value changes.
If you want to set a Trait, use can use the action setTrait
:
import React from 'react';
import { withTemper, setTrait } from 'temperjs';
function App() {
setTrait('count', 0);
return <Counter />
}
export default withTemper(App);
If you need to read from and write to a Trait, you can use the hook useTrait
:
import React from 'react';
import { useTrait } from 'temperjs';
function Counter() {
const [count, setCount] = useTrait('count');
function incrementCounter() {
setCount(({ value }) => value + 1);
}
function decrementCounter() {
setCount(({ value }) => value - 1);
}
return (
<div>
<p>{count}</p>
<button onClick={incrementCounter}>Increment</button>
<button onClick={decrementCounter}>Decrement</button>
</div>
);
}
export default Counter;
Selectors
Selectors are derived Traits. You can think of selectors as the output of passing a state to a pure function that executes some logic based on that state.
If you want to create a selector, you can use the following syntax:
import React from 'react';
import { withTemper, setTrait } from 'temperjs';
function App() {
// This is a simple Trait
setTrait('count', 0);
// This is a selector Trait
setTrait('isTargetReached', ({ get }) => get('count') >= 5);
return <Counter />
}
export default withTemper(App);
Selectors permanently depend on their reference Trait. When the reference Trait changes, the selector value is updated automatically.
Therefore, you cannot manually update selectors once set, since their value tightly depends on their base Trait.
Nested Traits
Temper encourages you to wrap related Traits in a single object. When a Trait is an object, each attribute will become a new Trait that is individually updatable and subscribable:
import React from 'react';
import { withTemper, setTrait } from 'temperjs';
function App() {
setTrait('counter', {
count: 0,
isTargetReached: ({ get }) => get('counter.count') >= 5
});
return <Counter />
}
export default withTemper(App);
If you just need to read a Trait, you can use the hook useTraitValue
(nested Traits are referenced with the dot notation.):
import React from 'react';
import { useTrait, useTraitValue } from 'temperjs';
function Counter() {
const [count, setCount] = useTrait('counter.count');
const isTargetReached = useTraitValue('counter.isTargetReached');
function incrementCounter() {
setCount(({ value }) => value + 1);
}
function decrementCounter() {
setCount(({ value }) => value - 1);
}
return (
<div>
<p>{count} { isTargetReached && (<span>You've reached the target!</span>)}</p>
<button onClick={incrementCounter}>Increment</button>
<button onClick={decrementCounter}>Decrement</button>
</div>
);
}
export default Counter;
Wrapping things up
Run the Counter on CodeSandbox.
API Documentation
Have a look at the documentation site for more details on Temper.