Overview

stan-js is a lightweight and flexible state management library designed for use in React, React Native and even vanilla-js applications. It simplifies the process of managing state in your application by providing a simple createStore function. This package aims to offer a straightforward solution for state management without the need for extensive type definitions or repetitive code.

Features

• ⚡️ Performance and minimal rerenders
• ✍️ Simple configuration
• ⚛️ Out of the box React intergration
• 🚀 Amazing typescript intellisense
• 🪝 Easy access to all store values
• 🪶 Very lightweight
• 🛡️ 100% Test coverage

Installation

Install package using preferred package manager:

npm install stan-js
# or
yarn add stan-js
# or
bun add stan-js

Demos

React

Astro + React

Getting Started

Create a store with initial state:

You can think of a store as your app state. You can define multiple keys/values, each key will create separated subscription (more explained here). If you want to persist the value - you can simply wrap it in Synchronizer

import { createStore } from 'stan-js'
import { storage } from 'stan-js/storage'

export const { useStore } = createStore({
    count: 0,
    user: storage(''),
    selectedLanguage: 'en-US',
    unreadNotifications: [] as Array<Notification>
})

Use the returned hook in your React component:

import { useStore } from './store'

const App = () => {
    const { count, user, setCount } = useStore()

    return (
        <div>
            <h1>Hello {user}!</h1>
            <p>Count: {count}</p>
            <button onClick={() => setCount(prev => prev + 1)}>Increment</button>
            <button onClick={() => setCount(prev => prev - 1)}>Decrement</button>
        </div>
    )
}

Check demos to play more with stan-js

Features

import { createStore } from 'stan-js'

export const { actions, getState, reset, effect, useStore, useStoreEffect } = createStore({
    count: 0,
    name: 'John',
    notifications: [] as Array<Notification>
})

actions

Object that contains all functions that allows for updating the store's state

Action name is generated automatically based on given key to the store count -> setCount

You can pass the next state directly, or a function that calculates it from the previous state - similary to the useState hook

getState

Function that returns current state of the store

const { count } = getState()

console.log(count)

reset

Function that resets store state to the initial values

You can either pass all of the keys that you want to be reset, or if you won't pass any key WHOLE store will be reseted.

reset('count')
// Only count value will be reseted

reset('name', 'notifications')
// name and notifications will be reseted

reset()
// Whole store will be reseted

effect

Function that allows to subscribe to store's values change and react to them

It takes callback with current store's state that will be triggered on every store's value that you are using

const dispose = effect(({ count }) => {
    console.log(count)
})

If you won't pass any key to the dependencies it will trigger only once at the start - similarly to the useEffect hook

useStore

React's hook that allows to access store's values and to update them

It ONLY rerenders the component if the values that we access have changed

const { count, setCount, setName } = useStore()

console.log(count)

setCount(prev => prev + 1) // Component will rerender
setName('Anna') // Component won't rerender because it doesn't subscribe to name

useStoreEffect

React's hook that uses effect under the hood

You should use it inside React components, and in the other places feel free to use effect

useStoreEffect(({ count }) => {
    console.log(count)
})

Synchronizer

Synchronizer is an util that allows you to synchronize store with something external like localStorage, database, device storage (MMKV, AsyncStorage) etc.

type Synchronizer<T> = {
    value: T,
    subscribe: (update: (value: T) => void, key: string) => void,
    // If synchronizer doesn't have data that matches passed key, it should throw
    getSnapshot: (key: string) => T | Promise<T>,
    update: (value: T, key: string) => void
}

There is already implementation for persisting data on both platforms (react and react-native).

import { storage } from 'stan-js/storage'

It takes two parameters - first is initial value, and the second one (which is optional) is options object with key (if the key isn't passed stan-js will pass key from the store), serialize and deserialize functions.

Important

For react-native you need to install react-native-mmkv and if you are using react-native older than 0.72 you need to add this to your metro.config.js

unstable_enablePackageExports: true,

Read more about it here

If you want to store more complex objects that aren't supported by JSON you can either write your own storage synchronizer or pass custom serialize and deserialize functions to the options parameter. For example, you can use superjson package:

import { createStore } from 'stan-js'
import { storage } from 'stan-js/storage'
import superjson from 'superjson'

const { useStore } = createStore({
    user: storage(new Set(), {
        serialize: superjson.stringify,
        deserialize: superjson.deserialize
    })
})

Scoped store

If your app is SSR or for example you just want to have the same store shape but keep different values for different routes you can use scoped store

It returns:

• StoreProvider - Provider that passes scoped store down to the React's tree
• withStore - HOC that passes scoped store down to the React's tree
• useScopedStore - React hook used to access scoped store

import { createScopedStore } from 'stan-js'

export const { StoreProvider, useScopedStore, withStore } = createScopedStore({
    count: 0,
})

Examples

SSR scoped store:

import { createScopedStore } from 'stan-js'

export const { StoreProvider, useScopedStore } = createScopedStore({
    count: 0,
    name: 'John'
})

// SSR Layout

<Layout>
    <StoreProvider initialValue={{ name: await db.getUser().name }}>
        {children}
    </StoreProvider>
</Layout>

// Some client component inside layout

const scopedStore = useScopedStore()
const { name } = scopedStore.useStore()

return (
    <h1>
        Hello {name}
    </h1>
)

Scoped store with regular routing

import { createScopedStore } from 'stan-js'

export const { StoreProvider, useScopedStore } = createScopedStore({
    count: 0,
    name: 'John'
})

const ProfileScreen = withStore(() => {
    // Component body...
})

// Some component inside ProfileScreen

const scopedStore = useScopedStore()
const { name } = scopedStore.useStore()

return (
    <h1>
        Hello {name}
    </h1>
)

Syncing values using synchronizer

storage

import { createStore } from 'stan-js'
import { storage } from 'stan-js/storage'

const { useStore } = createStore({
    counter: storage(0, { storageKey: 'counter-key' }), // number
    user: storage<string>(), // string | undefined
    cart: [] as Array<CartItem>
})