Synergies
Create a performant distributed context state by synergyzing atomar context pieces and composing reusable state logic.
synergies is a tiny (>3kB), yet powerful state management library for React. It allows you to specify small state atoms, that you can combine into Synergys of multiple atoms that define shared state logic. Features include
- Distributed state: You can inject individual atoms at multiple arbitrary points in your component hierarchy. You can also inject multiple atoms in one provider. Your state logic can not only read and write to the atoms provided by the closest provider, but to all atoms provided upwards in the component hierarchy.
- Immutable update logic:
synergiesusesimmerto provide drafts of your state in your update handlers, so you can more easily update state. - Performant update-triggers: Even though a synergy provider can provide several atoms and can access any atoms from other providers upwards the hierarchy, calling update logic will only trigger updates on components that read from atoms that were actually changed. Again
immeris used to let you update drafts of your state, and smartly detects which atoms were actually changed and which ones were only read during the update. - Asynchronous update logic: No more thunk extensions! Update handlers can be asynchronous, and you can even manually trigger updates on any atoms while still being in the middle of the update handler.
- Reusable state logic: Since you can provide atom state rather low down in the hierarchy, you can reuse small pieces of state between components, while still maintaining more global parts of your app state farther up in the component hierarchy.
- Typed: Full type safety for everything.
- Tiny package: 3kB + immer. Use it for your global app state, or just replace small context providers with
synergiesto simplify your codebase and speed up your state.
Usage
Get started by installing the library:
yarn add synergies immer
Create your first state atoms:
const valueAtom = createAtom("");
const isInitialStateAtom = createAtom(true);
Synergyze your atoms to create React Hooks:
const useSetValue = createSynergy(valueAtom, isInitialStateAtom).createAction(
(newValue: string) => (valueDraft, isInitialStateDraft) => {
// Components that read from the value atom will be updated.
valueDraft.current = newValue;
if (isInitialStateDraft.current) {
// If isInitialState is already false, then the draft will not be updated,
// and components that read from it will not trigger a rerender.
isInitialStateDraft.current = false;
}
}
);
// Every atom is also a synergy of itself, so we can call `createSelector` also on atoms.
const useValue = valueAtom.createSelector(value => value);
const useIsInitialState = isInitialStateAtom.useValue; // shortcut for directly reading atom state
Provide your atoms:
<SynergyProvider atoms={[valueAtom, isInitialStateAtom]}>
{/* Components that consume value and isInitialState... */}
{/* We can also nest other synergy providers */}
<SynergyProvider atoms={[moreLocalizedAtom]}>
{/* Can read from and write to all three atoms. */}
</SynergyProvider>
</SynergyProvider>
Use your hooks:
const Component = () => {
const setValue = useSetValue();
const value = useValue();
return (
<input
value={value}
onChange={e => setValue(e.target.value)}
/>
)
}
More advanced examples
Async update logic
synergies supports asynchronous update actions. You can also trigger atoms in the middle of an update handler, so that their subscribers get rerendered before the action has completed.
This is shown in the following example, where an API fetch call is dispatched in a action handler. The isLoading atom is updated to true immediately when the fetch is dispatched, while the update call continues to load the data from the server. Components reading the isLoading atom will be rerendered immediately. Once the data has loaded, we update the data atom with the fetched result, and update the isLoading atom is updated to false, triggering rerenders of all components that read from either the data or the isLoading atom.
Note that, if the isLoading atom would not rerender a second time at the end, only components subscribing to the data atom would be rerendered.
const isLoadingAtom = createAtom(false);
const dataAtom = createAtom(null);
// Async update handler
const useFetchData = createSynergy(dataAtom, isLoadingAtom).createAction(
() => async (data, isLoading) => {
isLoading.current = true;
// Trigger rerenders of all components that read from the `isLoading` atom.
// The `isLoading` draft will be discarded, so we need to use the new one
// that the `trigger` method returns.
isLoading = isLoading.trigger();
const res = await fetch("https://pokeapi.co/api/v2/pokemon/pikachu");
// Update the `data` and `isLoading` atoms
data.current = await res.json();
isLoading.current = false;
}
);
// For simplicity, read from both atoms at once
const usePokemonData = createSynergy(dataAtom, isLoadingAtom).createSelector(
(data, isLoading) => ({ data, isLoading })
);
export const Example = () => {
const { data, isLoading } = usePokemonData();
const fetchData = useFetchData();
const resetData = useReset();
return !data && !isLoading ? (
<Button onClick={fetchData}>Load Pokemon</Button>
) : isLoading ? (
<div>Loading...</div>
) : (
<div>
{data.name} has a height of {data.height} and the abilities{" "}
{data.abilities.map(({ ability }) => ability.name).join(", ")}
</div>
);
};
Nested synergy providers
// ---------------------
// Atoms
// ---------------------
const filterAtom = createAtom(false);
const itemsAtom = createAtom([
{ todo: "First Todo", checked: true },
{ todo: "Second Todo", checked: false },
{ todo: "Third Todo", checked: false },
]);
const inputValueAtom = createAtom("");
// ---------------------
// Selectors and state actions
// ---------------------
const useFilteredItems = createSynergy(itemsAtom, filterAtom).createSelector(
(items, filter) => items.filter(({ checked }) => !filter || checked)
);
const useAddTodo = createSynergy(itemsAtom, inputValueAtom).createAction(
() => (items, input) => {
items.current.push({ todo: input.current, checked: false });
input.current = "";
}
);
const useToggleTodo = itemsAtom.createAction((id: number) => items => {
items.current[id].checked = !items.current[id].checked;
});
const useToggleFilter = filterAtom.createAction(() => filter => {
filter.current = !filter.current;
});
// ---------------------
// Components that use the hooks
// ---------------------
const List = () => {
const items = useFilteredItems();
const toggle = useToggleTodo();
return (
<>
{items.map((item, index) => (
<Checkbox
key={index}
checked={item.checked}
label={item.todo}
onChange={() => toggle(index)}
/>
))}
</>
);
};
const TodoInput = () => {
const [value] = inputValueAtom.useValue();
const setValue = inputValueAtom.useSet();
const addTodo = useAddTodo();
return (
<ControlGroup>
<InputGroup
placeholder="Add a todo"
value={value}
onChange={e => setValue(e.target.value)}
/>
<Button onClick={addTodo}>Add</Button>
</ControlGroup>
);
};
const FilterButton = () => {
const toggle = useToggleFilter();
const [isToggled] = filterAtom.useValue();
return (
<Button onClick={toggle} active={isToggled}>
Only show completed todos
</Button>
);
};
// ---------------------
// App container
// ---------------------
export const App = () => (
// We don't have to nest the providers so extremely, but this demonstrates how you can inject
// atoms at any place in the hierarchy and they can still communicate upwards with other
// atoms.
<SynergyProvider atoms={[filterAtom]}>
<FilterButton />
<SynergyProvider atoms={[itemsAtom]}>
<List />
<SynergyProvider atoms={[inputValueAtom]}>
<TodoInput />
</SynergyProvider>
</SynergyProvider>
</SynergyProvider>
);
Maintenance
- Deployment automatically happens. Initialize GitHub Pages by going to the Repo's settings, scrolling down to GitHub Pages, selecting the
gh-pagesbranch and click on Save (root directory is fine). - Implement your components and hooks by copying the template packages. Make sure to adapt the package names, repository url and author in the respective
package.jsonfiles. - Make sure to remove the template packages if you don't need them anymore. You can always copy them from the original template repo again.
When developing locally, run in the root directory...
yarnto install dependenciesyarn testto run tests in all packagesyarn buildto build distributables and typings inpackages/{package}/outyarn storybookto run a local storybook serveryarn build-storybookto build the storybooknpx lerna versionto interactively bump the packages versions. This automatically commits the version, tags the commit and pushes to git remote.npx lerna publishto publish all packages to NPM that have changed since the last release. This automatically bumps the versions interactively.
8.7k Jan 8, 2023
7 Jul 31, 2022
65 Dec 29, 2022
4 Nov 28, 2022
24 Jun 20, 2022
18 Jun 15, 2021
24 Sep 6, 2022
19 Feb 22, 2022
23 Sep 25, 2022
3 Feb 4, 2022
2 May 15, 2022
0 Feb 7, 2022
9 Feb 21, 2022
5 Mar 11, 2022
53 Nov 5, 2022
148 Dec 26, 2022
12.6k Jan 3, 2023
18.2k Jan 8, 2023
25.5k Jan 9, 2023