App: Skill for Claude Code

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

Optimistic updates allow users to see changes immediately while the API request is queued. This is fundamental to Expensify's offline-first architecture.

For which pattern to use (A / B / C / D) and UX behavior for each, see https://github.com/Expensify/App/blob/main/contributingGuides/philosophies/OFFLINE.md.

Understanding the Three Data Sets

CRITICAL: Backend response data is automatically applied via Pusher updates or HTTPS responses. You do NOT manually set backend data in successData/failureData — only UI state cleanup goes there.

1. optimisticData (Applied immediately, before the API call)
   • Mirrors what the backend would return on success
   • Gives the user instant feedback without waiting for the server
   • Often includes pendingAction to flag the change as in-flight (e.g. greying out a comment while offline)
   • pendingAction is cleared once successData or failureData is applied