{"id":13527539,"url":"https://github.com/immobiliare/atomic-state","last_synced_at":"2026-03-11T10:32:24.401Z","repository":{"id":45892939,"uuid":"344839508","full_name":"immobiliare/atomic-state","owner":"immobiliare","description":"A decentralized state management library for React","archived":false,"fork":false,"pushed_at":"2021-11-29T09:32:03.000Z","size":2277,"stargazers_count":63,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-25T13:47:24.525Z","etag":null,"topics":["atomic-state","hooks","react","react-hooks","reactjs","recoil","recoiljs","state","state-atom","state-management","state-manager"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/immobiliare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-05T14:41:45.000Z","updated_at":"2025-07-08T17:51:51.000Z","dependencies_parsed_at":"2022-09-26T21:40:16.361Z","dependency_job_id":null,"html_url":"https://github.com/immobiliare/atomic-state","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/immobiliare/atomic-state","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fatomic-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fatomic-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fatomic-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fatomic-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immobiliare","download_url":"https://codeload.github.com/immobiliare/atomic-state/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fatomic-state/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30378084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomic-state","hooks","react","react-hooks","reactjs","recoil","recoiljs","state","state-atom","state-management","state-manager"],"created_at":"2024-08-01T06:01:50.624Z","updated_at":"2026-03-11T10:32:24.382Z","avatar_url":"https://github.com/immobiliare.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"logo.svg\" alt=\"AtomicState\" width=\"903\" height=\"177\" /\u003e\n\u003c/p\u003e\n\n![CI](https://github.com/immobiliare/atomic-state/workflows/CI/badge.svg)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)\n![bundlephobia](https://badgen.net/bundlephobia/minzip/@immobiliarelabs/atomic-state)\n\n\u003e A decentralized state management library for React\n\nSometimes 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).\n\nAtomicState brings to you a way to **share state** in a **simple** and **decentralized** way **without burdening your app size and complexity**.\n\n## Features Highlights\n\n-   💡 **Simple \u0026 Reactish**: Use AtomicState without learning new concepts because it works like the React API that you already know\n-   💡 **Small footprint**: AtomicState wieghts only 1.5Kb (gzip) on your production bundle\n-   💡 **SSR ready**: Server Side Rendering is a first-class citizen for AtomicState and it works like a breeze\n-   💡 **Integrated DevTools**: Install the official devtools from the Chrome Web Store and take a look in your atoms!\n-   💡 **Decentralized**: The state atoms can be loaded only when they are needed enabling you to do lazy load without troubles.\n\n## Table of contents\n\n-   [Quick start](#quick-start)\n-   [Setup](#setup)\n-   [What is an atom?](#what-is-an-atom)\n-   [Deriving state](#deriving-state)\n-   [Effects](#effects)\n-   [Server Side Rendering](#server-side-rendering)\n-   [DevTools](#devtools)\n-   [Powered Apps](#powered-apps)\n-   [Support \u0026 Contribute](#support-contribute)\n-   [License](#license)\n\n## Quick start\n\nSharing some state across components sometimes is more complex than it should be.\n\nWith AtomicState it will be clean and simple:\n\n`./doYouKnowAtomicState.js`\n\n```jsx\nimport { createStateAtom } from '@immobiliarelabs/atomic-state';\n\n// This is an atom a container for a piece of state\nexport const doYouKnowAtomicState = createStateAtom({\n    key: `DoYoyKnowAtomicState`, // unique ID\n    default: null, // default value (aka initial value)\n});\n```\n\nBy importing the created atom you can read and modify the state wherever you want:\n\n`./DoYoyKnowAtomicStateDisclamer.js`\n\n```jsx\nimport { useStateAtom } from '@immobiliarelabs/atomic-state';\nimport { doYouKnowAtomicState } from './doYouKnowAtomicState';\n\nexport function DoYoyKnowAtomicStateDisclamer() {\n    // useStateAtom is like a shared version of useState\n    const [answer, setAnswer] = useStateAtom(doYouKnowAtomicState);\n\n    if (answer) {\n        return null;\n    }\n\n    return (\n        \u003cdiv\u003e\n            Hey! Do you know AtomicState?\n            \u003cbutton onClick={() =\u003e setAnswer('yes')}\u003eYes!\u003c/button\u003e\n            \u003cbutton onClick={() =\u003e setAnswer('no')}\u003eNo!\u003c/button\u003e\n        \u003c/div\u003e\n    );\n}\n```\n\n`./DoYoyKnowAtomicStateLinks.js`\n\n```jsx\nimport { useStateAtom } from '@immobiliarelabs/atomic-state';\nimport { doYouKnowAtomicState } from './doYouKnowAtomicState';\n\nexport function DoYoyKnowAtomicStateLinks() {\n    const [answer] = useStateAtom(doYouKnowAtomicState);\n\n    if (answer === 'no') {\n        return (\n            \u003cdiv\u003e\n                Oh really!?! Take a look{' '}\n                \u003ca href=\"https://github.com/immobiliare/atomic-state\"\u003ehere\u003c/a\u003e,\n                it's easy to pick up!\n            \u003c/div\u003e\n        );\n    }\n\n    return null;\n}\n```\n\nThat's it and if you want to know more read the below docs!\n\n### Setup\n\nTo install the latest stable version, run the following command:\n\n```\nnpm install @immobiliarelabs/atomic-state\n```\n\nOr if you're using yarn:\n\n```\nyarn add @immobiliarelabs/atomic-state\n```\n\n### What is an atom?\n\nAn 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:\n\n```tsx\nimport { createStateAtom, useStateAtom } from '@immobiliarelabs/atomic-state';\n\nconst yourNameAtom = createStateAtom({\n    key: `YourName`, // unique ID\n    default: '', // default value (aka initial value)\n});\n\nfunction TextInput() {\n    // useStateAtom has the same behavior of useState\n    const [yourName, setYourName] = useStateAtom(yourNameAtom);\n\n    function handleChange(event) {\n        setYourName(event.target.value);\n    }\n\n    return (\n        \u003cdiv\u003e\n            \u003clabel htmlFor=\"your-name\"\u003eYour name:\u003c/label\u003e\n            \u003cinput\n                id=\"your-name\"\n                type=\"text\"\n                onChange={handleChange}\n                value={text}\n            /\u003e\n        \u003c/div\u003e\n    );\n}\n```\n\n### Deriving state\n\nDerived atoms can be used to derive information from other atoms. They cache their output and triggers an update only when their output changes.\n\nConceptually, 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.\n\n```tsx\nimport { createDerivedAtom, useAtomValue } from '@immobiliarelabs/atomic-state';\nimport { yourNameAtom } from './TextInput';\n\nconst yourNameIsFilledAtom = createDerivedAtom({\n    key: `YourName/Filled`, // unique ID\n    get(use) {\n        return use(yourNameAtom) !== '';\n    },\n});\n\nfunction TextInputFilledStatus() {\n    // useAtomValue reads the state from an atom\n    const filled = useAtomValue(yourNameIsFilledAtom);\n\n    return \u003cspan\u003e{filled ? 'Filled' : 'Empty'}\u003c/span\u003e;\n}\n```\n\n### Effects\n\nAtom effects are works in a similar way of React [useEffect](https://reactjs.org/docs/hooks-effect.html).\n\nThey have the same [cleanup](https://reactjs.org/docs/hooks-effect.html#effects-with-cleanup) api and are executed only on the client side.\n\n```tsx\nimport { createStateAtom, useStateAtom } from '@immobiliarelabs/atomic-state';\n\nconst persistentModeAtom = createStateAtom({\n    key: `PersistentMode`,\n    default: true,\n});\n\nconst textAtom = createStateAtom({\n    key: `Text`,\n    default: null,\n    setup(self, { effect, get, set }) {\n        /**\n            `effect` lets you run effects after the atom update\n\n            Like React.useEffect the effects are executed only in the browser after the paint\n        */\n        effect(\n            (open) =\u003e {\n                if (get(persistentModeAtom) !== true) return;\n\n                if (get(self) === null) {\n                    set(self, localStorage.getItem('LastEditedText') || '');\n                } else {\n                    localStorage.setItem('LastEditedText', get(self));\n                }\n            },\n            [self]\n        );\n    },\n});\n```\n\nUnder the hood the atom effects are managed through React useEffect, so even in your unit tests they will behave exactly like useEffect.\n\n### Server Side Rendering\n\nThe first thing you have to do is place the AtomicStateProvider on top of your applications.\n\nIt is possible to hydrate the atoms state by passing a state object to it.\n\n```tsx\nimport {\n    createStateAtom,\n    AtomicStateProvider,\n} from '@immobiliarelabs/atomic-state';\nimport { myFormAtom } from './atoms';\n\nfunction MyApp({ formInitialState }) {\n    /**\n     * Every update of this value will trigger a `setState` on the related atoms\n     *\n     * This makes easy to update the atom values on page navigations\n     */\n    const atomsState = useMemo(\n        () =\u003e ({\n            [myFormAtom.key]: formInitialState,\n        }),\n        [formInitialState]\n    );\n\n    return (\n        \u003cAtomicStateProvider state={atomsState}\u003e\n            \u003cAppCore /\u003e\n        \u003c/AtomicStateProvider\u003e\n    );\n}\n```\n\n### DevTools\n\nWe have a devtools extension for [Chrome](https://chrome.google.com/webstore/detail/atomic-state-devtools/mhdnjcangakajcinldiniomklbmmjcka)\n\nFor more info take a look into the [devtools docs](./devtools/README.md)\n\n## Powered Apps\n\nAtomicState was created by the amazing frontend team at ImmobiliareLabs, the Tech dept at Immobiliare.it, the first real estate site in Italy.  \nWe are currently using AtomicState in our products.\n\n**If you are using AtomicState in production [drop us a message](mailto://opensource@immobiliare.it)**.\n\n## Support \u0026 Contribute\n\nMade with ❤️ by [ImmobiliareLabs](https://github.com/immobiliare) \u0026 [Contributors](./CONTRIBUTING.md#contributors)\n\nWe'd love for you to contribute to AtomicState!\nIf you have any questions on how to use AtomicState, bugs and enhancement please feel free to reach out by opening a [GitHub Issue](https://github.com/immobiliare/atomic-state/issues).\n\n## License\n\nAtomicState is licensed under the MIT license.  \nSee the [LICENSE](./LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Fatomic-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmobiliare%2Fatomic-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Fatomic-state/lists"}