rgstate v1.0.12

RGState

React Global State

npm install rgstate --save
yarn add rgstate

The simplest implementation

import React, { useEffect } from 'react';
import { createGlobalState, useGlobalState } from 'rgstate';

// inspired by React.createContext
export const PostsState = createGlobalState([], { name: 'posts' });

export default function App() {
  // inspired by React.useState
  const [posts, setPosts] = useGlobalState(PostsState);

  useEffect(() => {
    const handleFetch = async () => {
      const result = await fetch('https://jsonplaceholder.typicode.com/posts');
      const data = await result.json();
      setPosts(data);
    };
    handleFetch();
  }, [setPosts]);

  return (
    <div>
      Fetched posts: {posts.length}
    </div>
  );
}

And that's all you need!

API

import {
    createGlobalState,
    useGlobalState,
    useGlobalSetter,
    useGlobalGetter
} from 'rgstate';

• createGlobalState to initialize your global state
• useGlobalState to get the [value, setter] variables
• useGlobalSetter to get the static setter only
• useGlobalGetter to get the reactive value only

createGlobalState

createGlobalState<T>(defaultValue: any, params: { name?: string; persist?: boolean }) => GlobalState<T>

• Initialize RGState like React's context, using createGlobalState and providing a default value

import { createGlobalState } from 'rgstate';

export const PostsState = createGlobalState([]);

Custom name - Recommended 🚨

Provide an optional key name for the internal store. If you skip this, a new uuid will be generated when the global state initializes. This causes issues with application hot reload where you could lose your stored data during development if you don't provide a key name.

export const PostsState = createGlobalState([], { name: 'posts' });

Sync with local storage

If you want to store your last data shape in your browser storage, use the persist: true config option

export const PostsState = createGlobalState([], { persist: true });

useGlobalState

useGlobalState(GlobalState) => value: T, setter: (handler: GlobalStateSetType<T>) => void

• Use it like React's state
• the useGlobalState hook returns values provided by useGlobalGetter and useGlobalSetter

import React from 'react';
import { useGlobalState } from 'rgstate';

import { PostsState } from './state';

const App = () => {
  const [posts, setPosts] = useGlobalState(PostsState);
}

useGlobalSetter

useGlobalSetter(GlobalState) => (handler: GlobalStateSetType<T>) => void

• In case you only need the setter and don't need the reactivity of the current value, opt in for using useGlobalSetter
• The returned method doesn't re-create and therefore it's safe to use it as a useEffect or useCallback dependency

import React from 'react';
import { useGlobalState } from 'rgstate';

import { PostsState } from './state';

const PostDelete = () => {
  const setPosts = useGlobalSetter(PostsState);
}

• The setter accepts
  • a value
  • a function, which provides you with the current value as a parameter, very similar to React's useState API

setPosts([{ id: 1, name: 'New Post' }])

setPosts((previousPosts) => {
    const newPosts = [...previousPosts]
    newPosts.slice(0, 1)
    return newPosts
})

useGlobalGetter

useGlobalGetter(GlobalState) => value: T

• When you don't need the setter and are only concerned about the current reactive value, use useGlobalGetter
• The returned value re-creates only when the value is directly changed and it's not affected by other global values changing

import React from 'react';
import { useGlobalGetter } from 'rgstate';

import { PostsState } from './state';

const PostDelete = () => {
  const posts = useGlobalGetter(PostsState);
}

As you introduce global states, global setters and global getters throughout your App, the values are stored in the same place. The setter accepts a function as a parameter and this function exposes the current value related to the setter as a parameter.

No matter how much you scale your app and how much global state properties you add, the implementation stays this simple.