onyx
Onyx state management patterns — useOnyx hook, action files, optimistic updates, collections, and offline-first architecture. Use when working with Onyx connections, writing action files, debugging state, or implementing API calls with optimistic data.
Best for React Native developers usi…Works with GitHub
⌘source
- author
@Expensify- repo
- Expensify/App
- language
- TypeScript
★4.8kstars
3.7kforks
Apr 22, 2026
✦overview.md
Key Features
- ·Persistent key-value storage with automatic AsyncStorage persistence
- ·Reactive subscriptions for data changes
- ·Collection management capabilities
- ·Offline-first architecture with optimistic updates
- ·Enforces action file pattern for state modification
Use Cases
- →Implementing optimistic UI updates while API requests are queued
- →Debugging state issues in Onyx-connected applications
- →Writing action files for state modifications
- →Building offline-first React Native applications
Best for
- ✓React Native developers using Onyx
- ✓Teams implementing offline-first architectures
- ✓Projects requiring persistent state management
Not ideal for
- !Simple state management needs without persistence requirements
- !Projects not using React Native
FAQs
name
onyx
description
Onyx state management patterns — useOnyx hook, action files, optimistic updates, collections, and offline-first architecture. Use when working with Onyx connections, writing action files, debugging state, or implementing API calls with optimistic data.
Core Concepts
Onyx is a persistent storage solution wrapped in a Pub/Sub library that enables reactive, offline-first data management — key-value storage with automatic AsyncStorage persistence, reactive subscriptions, and collection management.
For the full API reference (initialization, storage providers, cache eviction, benchmarks, Redux DevTools), see https://github.com/Expensify/react-native-onyx/blob/main/README.md.
Common Patterns
Action File Pattern
IMPORTANT: Onyx state must only be modified from action files (src/libs/actions/). Never call Onyx.merge, Onyx.set, Onyx.clear, or API.write directly from a component.
import Onyx from 'react-native-onyx';
import ONYXKEYS from '@src/ONYXKEYS';
function setIsOffline(isNetworkOffline: boolean, reason = '') {
if (reason) {
Log.info(`[Network] Client is ${isNetworkOffline ? 'offline' : 'online'} because: ${reason}`);
}
Onyx.merge(ONYXKEYS.NETWORK, {isOffline: isNetworkOffline});
}
export {setIsOffline};
Optimistic Updates Pattern
$install
1-click copynpx skills add Expensify/App --skill onyxSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
4/ 5
very goodClear and well structured, with only minor parts that might need a second read.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
3/ 5
mediumPartially actionable with several concrete steps, but still missing important details.