nexus-state
v1.6.5
Published
Global state manager✨
Downloads
1,267
Maintainers
Readme
nexus-state ✨
Table of contents
- About
- Installation
- InitialStates
- NexusProvider
- useNexus
- useNexusSelect
- nexusUpdate
- nexusTrigger
- Motivation
- API
About
A lightweight and flexible state management library for React
applications with TypeScript
support. With nexus-state
, you can easily build complex state structures.
While the library works with JavaScript, using TypeScript unlocks the full potential of type inference and autocompletion.
Installation
Install the library using the following command:
npm install nexus-state
InitialStates
Create a file, such as nexusConfig
, where you define initialStates
:
export const initialStates = {
strength: 10,
secretPower: 5,
// other states...
};
🛠 Configuring TypeScript for nexus-state
For TypeScript, extend the global StatesT
interface provided by the library. The simplest way is to use typeof
:
type InitialStatesT = typeof initialStates;
declare global {
interface StatesT extends InitialStatesT {}
}
The nexus-state
library comes with the default type _NEXUS_
in StatesT
. For more information, see the nexusUpdate
section.
🔮 Make sure to configure tsconfig
properly.
NexusProvider
Wrap your application with NexusProvider
, passing in initialStates
:
import { NexusProvider } from "nexus-state";
import { initialStates } from "./nexusConfig";
const App = () => (
<NexusProvider initialStates={initialStates}>
<YourComponent />
</NexusProvider>
);
useNexus
To access a state value, use the useNexus
hook:
import { useNexus } from "nexus-state";
const YourComponent = () => {
const strength = useNexus("strength");
return <p>`🧙♂️ Your strength is ${strength}`</p>;
};
🔮 If you call useNexus
empty then you will get all your states. This can be useful for debugging.
useNexusSelect
If you need to calculate derived data from the state, use the useNexusSelect
hook:
import { useNexusSelect } from "nexus-state";
const YourComponent = () => {
const fullPower = useNexusSelect(
(state) => state.strength + state.secretPower
);
return <p>`🧙♂️ Your full power is ${fullPower}`</p>;
};
nexusUpdate
To update the state, use the nexusUpdate
function. You can transmit values directly:
const levelUp = () => {
nexusUpdate({
strength: 15,
});
};
Or get the previous value and work with it:
const levelUp = () => {
nexusUpdate({
strength: (prevState) => prevState + 5,
});
};
You can also pass as many values as you want, you are limited only by the number of states you have created:
import { nexusUpdate } from "nexus-state";
const levelUp = () => {
nexusUpdate({
strength: (prevState) => prevState + 5,
secretPower: (prevState) => prevState + 1,
});
};
const YourButton = () => {
return <button onClick={levelUp}>`🧙♂️ Raise the level`</button>;
};
For use in nexusUpdate
, it supplies one default type _NEXUS_
to StatesT
. It is used to update all user states.
This can help you update all the states at one time they are stored remotely:
nexusUpdate({
_NEXUS_: fetchedData,
});
🎉 Hurray! You already have everything you need to start working with global states. Next are the additional features of nexus-state.
nexusTrigger
Since there are many disadvantages of storing functions in states and the practical impossibility of their further use, nexus-state
provides the possibility of creating a storage center for user functions and further calling them via nexusTrigger
.
To get started with the nexusTrigger
, you need to:
1. Define initialFuncs in your config:
export const initialFuncs = {
playerActions: {
fData: (payload) => {
console.log("Current player action:", payload);
},
},
// over funcs
};
For TypeScript, extend the global FuncsT
interface in the same way as StatesT
:
type InitialStatesT = typeof initialStates;
type InitialFuncsT = typeof initialFuncs;
declare global {
interface StatesT extends InitialStatesT {}
interface FuncsT extends InitialFuncsT {}
}
2. Transfer the initialFuncs to the NexusProvider
Wrap your application with NexusProvider
, passing in initialStates
:
import { NexusProvider } from "nexus-state;
import { initialStates, initialFuncs } from "./nexusConfig";
const App = () => (
<NexusProvider initialStates={initialStates} initialFuncs={initialFuncs}>
<YourComponent />
</NexusProvider>
);
3. Use nexusTrigger
import { nexusTrigger } from "nexus-state";
const actionDefiner = () => {
nexusTrigger({
type: "playerActions",
payload: "The hero waves his sword!",
});
};
const YourButton = () => {
return <button onClick={actionDefiner}>`🧙♂️ What does the hero do?`</button>;
};
So you can use nexusTrigger
, but its true power is shown in using it together with nexusUpdate
, as it is also a simple function.
This way you can think through complex user logic:
import { nexusUpdate } from "nexus-state";
const powerUp = {
fData: ({ param, data }) => {
switch (param) {
case "strength": {
nexusUpdate({
strength: (prevState) => prevState + data,
});
return;
}
case "secretPower": {
nexusUpdate({
secretPower: (prevState) => prevState + data,
});
return;
}
default:
return;
}
},
};
export const initialFuncs = {
powerUp,
// over funcs
};
In this example, we have created a function
with a switch
case
design and the ability to change the desired state.
Usage example:
import { nexusTrigger } from "nexus-state";
const powerUpCall = () => {
nexusTrigger({
type: "powerUp",
payload: {
param: "strength",
data: 5,
},
});
};
const YourButton = () => {
return (
<button onClick={powerUpCall}>`🧙♂️ Increase the desired parameter`</button>
);
};
Problems
No-empty-object-type error:
If you use eslint
, you might encounter an error about empty object types (@typescript-eslint/no-empty-object-type
), but this is easy to fix:
1. Add a rule to eslint:
rules: {
"@typescript-eslint/no-empty-object-type": "off",
}
2. Define all states manually if there are only a few:
declare global {
interface StatesT {
strength: number;
secretPower: number;
}
}
3. Simply ignore the warning. 🙌
Motivation
This library came about by chance. I hadn't planned on using a state manager and simply updated states based on a flux-like architecture. Over time, I wanted to isolate state management into a separate component, which led to the creation of this library.
The name "Nexus" was inspired by the game Demon's Souls, where the "Nexus" serves as a safe haven for the player and a starting point. Similarly, with nexus-state
, I wanted users to feel connected to a place like the "Nexus" or a bonfire from Dark Souls, where they can start their journey to anywhere.
🔥🗡️
I hope using nexus-state
makes your development enjoyable and productive! ✨
API
NexusProvider
: Provider Component to wrap your application.useNexus
: Hook for accessing a state by key.useNexusSelect
: Hook for computed or derived state values.nexusUpdate
: Function to update your states.nexusTrigger
: Function to dispatch actions.