Features

Why

Installation

pnpm add jotai jotai-x

Quick Start

import{createAtomStore}from'jotai-x';// Create a store with an initial state// Store name is used as prefix for all returned hooks (e.g., `useAppStore`, `useAppValue` for `name: 'app'`)const{ useAppStore, useAppValue, useAppSet, useAppState, AppProvider}=createAtomStore({name:'JotaiX',stars:0,},{name:'app',});// Use it in your componentsfunctionRepoInfo(){constname=useAppValue('name');conststars=useAppValue('stars');return(<div><h1>{name}</h1><p>{stars} stars</p></div>);}functionAddStarButton(){constsetStars=useAppSet('stars');return<buttononClick={()=>setStars((s)=>s+1)}>Add star</button>;}

Core Concepts

Store Configuration

import{createAtomStore}from'jotai-x';// Types are inferred, including optionsconst{ useUserValue, useUserSet, useUserState, UserProvider}=createAtomStore({name:'Alice',loggedIn:false,},{name:'user',delay:100,// Optional delay for state updateseffect:EffectComponent,// Optional effect componentextend:(atoms)=>({// Optional derived atomsintro:atom((get)=>`My name is${get(atoms.name)}`),}),infiniteRenderDetectionLimit:100,// Optional render detection limit});

{  name:string;  delay?:number;  effect?:React.ComponentType;  extend?:(atoms:Atoms)=>DerivedAtoms;  infiniteRenderDetectionLimit?:number;}

Store API

const{// Store name used as prefixname:string,// Store hook returning all utilitiesuseAppStore:()=>StoreApi,// Direct hooks for state managementuseAppValue:(key:string,options?)=>Value,useAppSet:(key:string)=>SetterFn,useAppState:(key:string)=>[Value,SetterFn],// Provider componentAppProvider:React.FC<ProviderProps>,// Record of all atoms in the storeappStore:{atom:Record<string,Atom>}}=createAtomStore({ ...},{name:'app'});

Reading and Writing State

1. Hooks (Recommended)

// Get valueconstname=useAppValue('name');conststars=useAppValue('stars');// Set valueconstsetName=useAppSet('name');constsetStars=useAppSet('stars');// Get both value and setterconst[name,setName]=useAppState('name');const[stars,setStars]=useAppState('stars');// With selector and depsconstupperName=useAppValue('name',{selector:(name)=>name.toUpperCase(),},[]);

2. Store Instance Methods

conststore=useAppStore();// By keystore.get('name');// Get valuestore.set('name','value');// Set valuestore.subscribe('name',(value)=>console.log(value));// Subscribe to changes// Direct accessstore.getName();// Get valuestore.setName('value');// Set valuestore.subscribeName((value)=>console.log(value));// Subscribe to changes

3. Raw Atom Access

conststore=useAppStore();// Access atomsstore.getAtom(someAtom);// Get atom valuestore.setAtom(someAtom,'value');// Set atom valuestore.subscribeAtom(someAtom,(value)=>{});// Subscribe to atom// Access underlying Jotai storeconstjotaiStore=store.store;

Hook API Reference

use<Name>Value(key, options?)

// Basic usageconstname=useAppValue('name');// With selectorconstupperName=useAppValue('name',{selector:(name)=>name.toUpperCase(),},[]// if selector is not memoized, provide deps array);// With equality functionconstname=useAppValue('name',{selector:(name)=>name,equalityFn:(prev,next)=>prev.length===next.length},[]);

use<Name>Set(key)

constsetName=useAppSet('name');setName('new value');setName((prev)=>prev.toUpperCase());

use<Name>State(key)

functionUserForm(){const[name,setName]=useAppState('name');const[email,setEmail]=useAppState('email');return(<form><inputvalue={name}onChange={(e)=>setName(e.target.value)}/><inputvalue={email}onChange={(e)=>setEmail(e.target.value)}/></form>);}

Provider-Based Store Hydration

typeProviderProps<T>={// Initial values for atoms, hydrated once on mountinitialValues?:Partial<T>;// Dynamic values for controlled state  ...Partial<T>;// Optional custom store instancestore?:JotaiStore;// Optional scope for nested providersscope?:string;// Optional key to reset the storeresetKey?:any;children:React.ReactNode;};functionApp(){return(<UserProvider// Initial values hydrated on mountinitialValues={{name:'Alice',email:'alice@example.com'}}// Controlled values that sync with the storename="Bob"// Optional scope for nested providersscope="user1"// Optional key to reset store stateresetKey={version}><UserProfile/></UserProvider>);}

Scoped Providers

functionApp(){return(<UserProviderscope="parent"name="Parent User"><UserProviderscope="child"name="Child User"><UserProfile/></UserProvider></UserProvider>);}functionUserProfile(){// Get parent scopeconstparentName=useUserValue('name',{scope:'parent'});// Get closest scopeconstname=useUserValue('name');}

Derived Atoms

// 1. Using extendconst{ useUserValue}=createAtomStore({name:'Alice',},{name:'user',extend:(atoms)=>({intro:atom((get)=>`My name is${get(atoms.name)}`),}),});// Access the derived value using the store nameconstintro=useUserValue('intro');// 2. External atomsconst{ userStore, useUserStore}=createAtomStore({name:'Alice',},{name:'user',});// Create an external atomconstintroAtom=atom((get)=>`My name is${get(userStore.atom.name)}`);// Create a writable external atomconstcountAtom=atom((get)=>get(userStore.atom.name).length,(get,set,newCount:number)=>{set(userStore.atom.name,'A'.repeat(newCount));});// Get the store instanceconststore=useUserStore();// Access external atoms using store-based atom hooksconstintro=useAtomValue(store,introAtom);// Read-only atomconst[count,setCount]=useAtomState(store,countAtom);// Read-write atomconstsetCount2=useSetAtom(store,countAtom);// Write-only// With selector and depsconstupperIntro=useAtomValue(store,introAtom,(intro)=>intro.toUpperCase(),[]// Optional deps array for selector);// With selector and equality functionconstintro2=useAtomValue(store,introAtom,(intro)=>intro,(prev,next)=>prev.length===next.length// Optional equality function);

Troubleshooting

Infinite Render Detection

// ❌ Wrong - will cause infinite rendersuseUserValue('name',{selector:(name)=>name.toUpperCase()});// ✅ Correct - memoize with useCallbackconstselector=useCallback((name)=>name.toUpperCase(),[]);useUserValue('name',{ selector});// ✅ Correct - provide deps arrayuseUserValue('name',{selector:(name)=>name.toUpperCase()},[]);// ✅ Correct - no selectoruseUserValue('name');

Migration from v1 to v2

// Beforeconst{ useAppStore}=createAtomStore({name:'Alice'},{name:'app'});constname=useAppStore().get.name();constsetName=useAppStore().set.name();const[name,setName]=useAppStore().use.name();// Nowconst{ useAppStore, useAppValue, useAppSet, useAppState}=createAtomStore({name:'Alice'},{name:'app'});constname=useAppValue('name');constsetName=useAppSet('name');const[name,setName]=useAppState('name');

License