{"id":29166313,"url":"https://github.com/sinhaparth5/nucleus-state","last_synced_at":"2026-04-29T19:02:57.055Z","repository":{"id":301587120,"uuid":"1009691729","full_name":"sinhaparth5/nucleus-state","owner":"sinhaparth5","description":"Lightweight React state management for UI components","archived":false,"fork":false,"pushed_at":"2026-03-16T22:41:30.000Z","size":239,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-17T08:54:53.718Z","etag":null,"topics":["management","react","state"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nucleus-state","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinhaparth5.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-27T14:48:54.000Z","updated_at":"2026-03-16T22:41:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"3aedab3b-a564-4091-af26-9c60772d0e3b","html_url":"https://github.com/sinhaparth5/nucleus-state","commit_stats":null,"previous_names":["sinhaparth5/nucleus-state"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sinhaparth5/nucleus-state","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhaparth5%2Fnucleus-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhaparth5%2Fnucleus-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhaparth5%2Fnucleus-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhaparth5%2Fnucleus-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinhaparth5","download_url":"https://codeload.github.com/sinhaparth5/nucleus-state/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhaparth5%2Fnucleus-state/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32439301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T18:12:22.909Z","status":"ssl_error","status_checked_at":"2026-04-29T18:11:33.322Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["management","react","state"],"created_at":"2025-07-01T08:37:10.878Z","updated_at":"2026-04-29T19:02:57.049Z","avatar_url":"https://github.com/sinhaparth5.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nucleus State\n\nLightweight React state management for shared UI state.\n\n[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6.svg)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-19+-61DAFB.svg)](https://react.dev/)\n\nNucleus State is a small TypeScript-first state library for React. It is designed for state that needs to be shared across components without adding providers, reducers, or heavy store setup.\n\nIt works well for:\n\n- modals and drawers\n- tabs and view state\n- theme and preference state\n- form steps and temporary UI data\n- small derived values built from existing atoms\n\n## Installation\n\n```bash\nnpm install @sinhaparth5/nucleus-state\n```\n\n## Quick Start\n\n```tsx\nimport { createAtom, useAtom } from '@sinhaparth5/nucleus-state';\n\nconst modalAtom = createAtom(false, { name: 'modal' });\n\nfunction OpenButton() {\n  const [, setModalOpen] = useAtom(modalAtom);\n  return \u003cbutton onClick={() =\u003e setModalOpen(true)}\u003eOpen modal\u003c/button\u003e;\n}\n\nfunction Modal() {\n  const [isOpen, setModalOpen] = useAtom(modalAtom);\n\n  if (!isOpen) {\n    return null;\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eSettings\u003c/p\u003e\n      \u003cbutton onClick={() =\u003e setModalOpen(false)}\u003eClose\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Why Nucleus State\n\n- Provider-free API\n- Small surface area\n- TypeScript-first ergonomics\n- Read/write hooks that feel like React state\n- Built-in persistence helpers\n- Derived state with computed atoms\n- Development-time atom registry for debugging\n\n## API\n\n### `createAtom(initialValue, options?)`\n\nCreates a mutable atom with `get()`, `set()`, `reset()`, and `subscribe()`.\n\n```tsx\nconst countAtom = createAtom(0);\nconst themeAtom = createAtom('light', { persist: 'theme' });\n```\n\nOptions:\n\n- `name`: debug label for development tooling\n- `persist`: storage key used for persistence\n- `storage`: custom storage object with `getItem` and `setItem`\n\n### `useAtom(atom)`\n\nReturns the current value and setter.\n\n```tsx\nconst [count, setCount] = useAtom(countAtom);\n\nsetCount(1);\nsetCount(prev =\u003e prev + 1);\n```\n\n### `useAtomValue(atom)`\n\nReturns the current value only.\n\n```tsx\nconst theme = useAtomValue(themeAtom);\n```\n\n### `useSetAtom(atom)`\n\nReturns the setter only.\n\n```tsx\nconst setTheme = useSetAtom(themeAtom);\n```\n\n### `atom.reset()`\n\nRestores an atom to its original initial value.\n\n```tsx\nconst countAtom = createAtom(0);\n\ncountAtom.set(5);\ncountAtom.reset();\n\ncountAtom.get(); // 0\n```\n\n### `createComputed(dependencies, compute)`\n\nCreates a read-only derived atom that updates from other atoms.\n\n```tsx\nimport {\n  createAtom,\n  createComputed,\n  useAtomValue,\n} from '@sinhaparth5/nucleus-state';\n\nconst firstNameAtom = createAtom('Parth');\nconst lastNameAtom = createAtom('Sinha');\n\nconst fullNameAtom = createComputed(\n  [firstNameAtom, lastNameAtom],\n  () =\u003e `${firstNameAtom.get()} ${lastNameAtom.get()}`,\n);\n\nfunction ProfileName() {\n  const fullName = useAtomValue(fullNameAtom);\n  return \u003ch1\u003e{fullName}\u003c/h1\u003e;\n}\n```\n\nYou can also use the simple form:\n\n```tsx\nconst timestampAtom = createComputed(() =\u003e Date.now());\n```\n\nThat form computes once and does not subscribe to dependencies automatically.\n\n## Persistence\n\nAtoms can persist state in browser storage and safely fall back when storage is unavailable.\n\n```tsx\nconst settingsAtom = createAtom(\n  { notifications: true, language: 'en' },\n  { persist: 'user-settings' },\n);\n```\n\nFor convenience, the package also exports:\n\n```tsx\nimport {\n  createPersistedAtom,\n  createSessionAtom,\n} from '@sinhaparth5/nucleus-state';\n\nconst themeAtom = createPersistedAtom('light', 'theme');\nconst wizardAtom = createSessionAtom({ step: 1 }, 'wizard');\n```\n\nCustom storage is supported:\n\n```tsx\nconst draftAtom = createAtom(\n  { value: '' },\n  {\n    persist: 'draft',\n    storage: {\n      getItem: key =\u003e sessionStorage.getItem(key),\n      setItem: (key, value) =\u003e sessionStorage.setItem(key, value),\n    },\n  },\n);\n```\n\n## Devtools\n\nIn development, named atoms are exposed on `window.__NUCLEUS_ATOMS__`.\n\n```tsx\nconst userAtom = createAtom(null, { name: 'currentUser' });\n\nconsole.log(window.__NUCLEUS_ATOMS__?.list());\nconsole.log(window.__NUCLEUS_ATOMS__?.get('currentUser'));\n```\n\n## TypeScript\n\nThe package is designed for strong type inference out of the box.\n\n```tsx\ninterface User {\n  id: number;\n  name: string;\n}\n\nconst userAtom = createAtom\u003cUser | null\u003e(null);\n\nconst [user, setUser] = useAtom(userAtom);\nconst userName = useAtomValue(userAtom)?.name;\n```\n\n## Examples\n\nExample source lives in:\n\n- `examples/basic-usage/App.tsx`\n- `examples/modal-management/App.tsx`\n- `examples/form-wizard/App.tsx`\n\nA runnable playground is available in `examples/playground`.\n\n```bash\npnpm example:dev\n```\n\n## Share on Twitter/X\n\nUse this post if you want to share the project:\n\n```text\nBuilt `nucleus-state` for lightweight shared React state without providers or store boilerplate.\n\n- TypeScript-first\n- atom-based API\n- computed state\n- persistence helpers\n\nRepo: https://github.com/sinhaparth5/nucleus-state\n\n#react #typescript #opensource #webdev\n```\n\n## Requirements\n\n- React `^19.1.0`\n- TypeScript `4.1+`\n\n## License\n\nBSD-2-Clause © [Parth Sinha](https://github.com/sinhaparth5)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhaparth5%2Fnucleus-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinhaparth5%2Fnucleus-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhaparth5%2Fnucleus-state/lists"}