npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@immobiliarelabs/atomic-state

v1.0.2

Published

A decentralized state management library for React inspired by Recoil.js

Downloads

22

Readme

CI code style: prettier Commitizen friendly bundlephobia

A decentralized state management library for React

Sometimes when you have to share some state between components you also add some complexity to it (lifting the state up, adding a context or dirtying your global state manager).

AtomicState brings to you a way to share state in a simple and decentralized way without burdening your app size and complexity.

Features Highlights

  • 💡 Simple & Reactish: Use AtomicState without learning new concepts because it works like the React API that you already know
  • 💡 Small footprint: AtomicState wieghts only 1.5Kb (gzip) on your production bundle
  • 💡 SSR ready: Server Side Rendering is a first-class citizen for AtomicState and it works like a breeze
  • 💡 Integrated DevTools: Install the official devtools from the Chrome Web Store and take a look in your atoms!
  • 💡 Decentralized: The state atoms can be loaded only when they are needed enabling you to do lazy load without troubles.

Table of contents

Quick start

Sharing some state across components sometimes is more complex than it should be.

With AtomicState it will be clean and simple:

./doYouKnowAtomicState.js

import { createStateAtom } from '@immobiliarelabs/atomic-state';

// This is an atom a container for a piece of state
export const doYouKnowAtomicState = createStateAtom({
    key: `DoYoyKnowAtomicState`, // unique ID
    default: null, // default value (aka initial value)
});

By importing the created atom you can read and modify the state wherever you want:

./DoYoyKnowAtomicStateDisclamer.js

import { useStateAtom } from '@immobiliarelabs/atomic-state';
import { doYouKnowAtomicState } from './doYouKnowAtomicState';

export function DoYoyKnowAtomicStateDisclamer() {
    // useStateAtom is like a shared version of useState
    const [answer, setAnswer] = useStateAtom(doYouKnowAtomicState);

    if (answer) {
        return null;
    }

    return (
        <div>
            Hey! Do you know AtomicState?
            <button onClick={() => setAnswer('yes')}>Yes!</button>
            <button onClick={() => setAnswer('no')}>No!</button>
        </div>
    );
}

./DoYoyKnowAtomicStateLinks.js

import { useStateAtom } from '@immobiliarelabs/atomic-state';
import { doYouKnowAtomicState } from './doYouKnowAtomicState';

export function DoYoyKnowAtomicStateLinks() {
    const [answer] = useStateAtom(doYouKnowAtomicState);

    if (answer === 'no') {
        return (
            <div>
                Oh really!?! Take a look{' '}
                <a href="https://github.com/immobiliare/atomic-state">here</a>,
                it's easy to pick up!
            </div>
        );
    }

    return null;
}

That's it and if you want to know more read the below docs!

Setup

To install the latest stable version, run the following command:

npm install @immobiliarelabs/atomic-state

Or if you're using yarn:

yarn add @immobiliarelabs/atomic-state

What is an atom?

An atom represents a piece of state. Atoms can be read from and written to from any component. Components that read the value of an atom are implicitly subscribed to that atom, so any atom updates will result in a re-render of all components subscribed to that atom:

import { createStateAtom, useStateAtom } from '@immobiliarelabs/atomic-state';

const yourNameAtom = createStateAtom({
    key: `YourName`, // unique ID
    default: '', // default value (aka initial value)
});

function TextInput() {
    // useStateAtom has the same behavior of useState
    const [yourName, setYourName] = useStateAtom(yourNameAtom);

    function handleChange(event) {
        setYourName(event.target.value);
    }

    return (
        <div>
            <label htmlFor="your-name">Your name:</label>
            <input
                id="your-name"
                type="text"
                onChange={handleChange}
                value={text}
            />
        </div>
    );
}

Deriving state

Derived atoms can be used to derive information from other atoms. They cache their output and triggers an update only when their output changes.

Conceptually, they are very similar to formulas in spreadsheets, and can't be underestimated. They help in reducing the amount of state you have to store and are highly optimized. Use them wherever possible.

import { createDerivedAtom, useAtomValue } from '@immobiliarelabs/atomic-state';
import { yourNameAtom } from './TextInput';

const yourNameIsFilledAtom = createDerivedAtom({
    key: `YourName/Filled`, // unique ID
    get(use) {
        return use(yourNameAtom) !== '';
    },
});

function TextInputFilledStatus() {
    // useAtomValue reads the state from an atom
    const filled = useAtomValue(yourNameIsFilledAtom);

    return <span>{filled ? 'Filled' : 'Empty'}</span>;
}

Effects

Atom effects are works in a similar way of React useEffect.

They have the same cleanup api and are executed only on the client side.

import { createStateAtom, useStateAtom } from '@immobiliarelabs/atomic-state';

const persistentModeAtom = createStateAtom({
    key: `PersistentMode`,
    default: true,
});

const textAtom = createStateAtom({
    key: `Text`,
    default: null,
    setup(self, { effect, get, set }) {
        /**
            `effect` lets you run effects after the atom update

            Like React.useEffect the effects are executed only in the browser after the paint
        */
        effect(
            (open) => {
                if (get(persistentModeAtom) !== true) return;

                if (get(self) === null) {
                    set(self, localStorage.getItem('LastEditedText') || '');
                } else {
                    localStorage.setItem('LastEditedText', get(self));
                }
            },
            [self]
        );
    },
});

Under the hood the atom effects are managed through React useEffect, so even in your unit tests they will behave exactly like useEffect.

Server Side Rendering

The first thing you have to do is place the AtomicStateProvider on top of your applications.

It is possible to hydrate the atoms state by passing a state object to it.

import {
    createStateAtom,
    AtomicStateProvider,
} from '@immobiliarelabs/atomic-state';
import { myFormAtom } from './atoms';

function MyApp({ formInitialState }) {
    /**
     * Every update of this value will trigger a `setState` on the related atoms
     *
     * This makes easy to update the atom values on page navigations
     */
    const atomsState = useMemo(
        () => ({
            [myFormAtom.key]: formInitialState,
        }),
        [formInitialState]
    );

    return (
        <AtomicStateProvider state={atomsState}>
            <AppCore />
        </AtomicStateProvider>
    );
}

DevTools

We have a devtools extension for Chrome

For more info take a look into the devtools docs

Powered Apps

AtomicState was created by the amazing frontend team at ImmobiliareLabs, the Tech dept at Immobiliare.it, the first real estate site in Italy.
We are currently using AtomicState in our products.

If you are using AtomicState in production drop us a message.

Support & Contribute

Made with ❤️ by ImmobiliareLabs & Contributors

We'd love for you to contribute to AtomicState! If you have any questions on how to use AtomicState, bugs and enhancement please feel free to reach out by opening a GitHub Issue.

License

AtomicState is licensed under the MIT license.
See the LICENSE file for more information.