GX – Global State Management for React Applications

This library aims to provide you an easy and fast way to set up and manage the global state of your react application.

Installation

You can use npm or yarn to install this library into your react application.

Using npm

npm install gx

Using yarn

yarn add gx

Prerequisites

This library doesn’t work properly in strict mode. So to avoid some issues, please disable strict mode in your react application first before using it.

Disabling strict mode on React

Before

import React, { StrictMode } from "react";

function App() {
  return (
    <StrictMode>
      { 
        // Your application here
      }
    </StrictMode>
  );
}

After

import React, { Fragment } from "react";

function App() {
  return (
    <Fragment>
      { 
        // Your application here
      }
    </Fragment>
  );
}

Disabling strict mode on Next.js

Open the next.config.js file and add the following code.

module.exports = {
  reactStrictMode: false,
};

Definition of concepts

GX comes with some new concepts like signal, action and store.

1. Signal

Signal represent a specific state that your application has to manage. For example, for managing users and products inside your ecommerce application you will have to create two separate signals called usersSignal and productsSignal.

For handle it, there is a special createSignal function for this case.

2. Action

Actions represent functions that act to the state and make it changing over the time.

Your have to specify these actions when you create yours signals.

3. Store

Store is a collection of signals. We know that in an application, we can manage many state separately, so gx gives you the possibility to centralize all your state into a special place. The state becomes easier to manage like that.

For handle it, there is a special createStore function for this case, which takes an array of signals.

Usage

First step: Setting up the code structure.

For structuring your code very well you have to follow these steps.

• Create a directory called gx or whatever you want inside the src directory
• Inside the gx directory, create two others one called signals and store.
• Inside the signals directory you will create files that will contains your state declaration with actions that act to this state. (ie: counter.js)
• Inside the store directory, just create an index.js file. We will see how to fill it.

Here is the result.

Second step: Creating your signals.

Inside the signals directory, create a file called counter.js for example.

import { createSignal } from 'gx';

const counterSignal = createSignal({
  name: 'counter',
  state: 0,
  actions: {
    increment: (state, payload) => {
      return state + payload;
    },

    decrement: (state, payload) => {
      return state - payload;
    }
  }
});

export default counterSignal;

Third step: Creating your store.

Inside the store directory, create an index.js file.

import { createStore } from "gx";
import counterSignal from "../signals/counter";

export default createStore([counterSignal]);

Fourth step: Using your store.

Inside your App.js file, import your store and wrap your application with the GXProvider component.

import React from "react";
import store from "./gx/store";
import GXProvider from "gx";

function App() {
  return (
    <GXProvider store={store}>
      { 
        // Your application here
      }
    </GXProvider>
  );
}

export default App;

Fifth step: Using your signals.

Create a component called Counter inside the Counter.js file. Then import two hooks from gx called useSignal and useAction like follow.

import React from "react";
import { useSignal, useAction } from "gx";

function Counter() {
  // State
  const counter = useSignal("counter");

  // Actions
  const { increment, decrement } = useAction("counter");

  return (
    <div>
      <h1>Counter App</h1>

      <p>Count: {counter}</p>

      <button onClick={() => increment(1)}>Increment</button>
      <button onClick={() => decrement(1)}>Decrement</button>
    </div>
  );
}

Note that the useSignal hook takes the name of the signal as a parameter and return the state contained inside that signal.

The useAction hook takes the name of the signal too and returns an object that contains all the actions of this signal.

Actually, if you click on the increment button, the counter will increase by one and if you click on the decrement button, the counter will decrease by one.

API

createSignal

This function takes an object as a parameter and returns a signal.

The object must contain the following properties:

Structure of the actions object:

{
  actionName: (state, payload) => {
    // Do something with the state and the payload
    return state;
  }
}

All actions must return the new state of the signal.

createStore

This function takes an array of signals as a parameter and returns a store.

const store = createStore([signal1, signal2, signal3]);

GXProvider

This component takes a store as a parameter and wraps your application with it.

const App = () => (
  <GXProvider store={store}>
    { 
      // Your application here
    }
  </GXProvider>
);

useSignal

This hook takes the name of the signal as a parameter and returns the state contained inside that signal.

const counter = useSignal("counter");

useAction

This hook takes the name of the signal as a parameter and returns an object that contains all the actions of this signal.

const { increment, decrement } = useAction("counter");

License

MIT

Author

• Github: @dilane3
• Twitter: @dilanekombou
• LinkedIn: @dilanekombou
• website: dilane3.com

Contributing

Contributions, issues and feature requests are welcome! See the Contributing Guide.

Keywords

react, state, management, hooks, gx

GitHub

View Github