react-native-onyx

3.0.71 verified Fri May 01 auth: no javascript

Persistent state management library for React Native, wrapping pub/sub patterns around AsyncStorage-like backends. Current version 3.0.71, active development, with frequent releases. Key differentiators: automatic persistent storage, collection-oriented key design (e.g., report_1234), React hooks (useOnyx) and non-React subscribers (Onyx.connect). Requires idb-keyval, react-native-device-info, react-native-nitro-modules, and react-native-nitro-sqlite as peer dependencies. Ships TypeScript definitions, supports browser bundling via Webpack. Unlike Redux or MobX, Onyx is tailored for React Native's offline-first, persistent-storage needs with minimal boilerplate.

Common errors

error Cannot find module 'react-native-onyx' or its corresponding type declarations. ↓

cause TypeScript project missing @types/react-native-onyx or old resolution

fix

Ensure react-native-onyx is installed: npm install react-native-onyx. For TS, add to tsconfig.json: "moduleResolution": "node" or "bundler"

error TypeError: Onyx.init is not a function ↓

cause Importing Onyx as a named export instead of default (e.g., import { Onyx } from 'react-native-onyx')

fix

Use default import: import Onyx from 'react-native-onyx'

error Onyx.merge only works with objects or arrays, not primitives ↓

cause Calling Onyx.merge with a string or number

fix

Use Onyx.set for primitive values, or wrap in an object: Onyx.merge(KEY, { value: 'string' })

error Onyx.connect callback is not called for existing data ↓

cause Misunderstood init and connect order – Onyx.connect will callback with current data only after Onyx.init is called

fix

Ensure Onyx.init is called before any Onyx.connect, and that the key exists in storage or has been set

Warnings

breaking Version 3.0+ drops AsyncStorage and requires idb-keyval, react-native-nitro-modules, and react-native-nitro-sqlite peer deps. ↓

fix npm install react-native-onyx@latest idb-keyval react-native-device-info react-native-nitro-modules react-native-nitro-sqlite

gotcha Object keys must not contain the collection separator '_' unless they are part of a collection. Using 'report_123' collides with ONYXKEYS.COLLECTION.REPORT pattern. ↓

fix Name non-collection keys without underscore, e.g., 'reportData' instead of 'report_data'

gotcha Onyx.set with an array replaces the entire array; Onyx.merge with array also replaces (unexpected). To append, read current value first and merge manually. ↓

fix const current = await Onyx.get(KEY); const updated = [...current, newItem]; Onyx.set(KEY, updated);

deprecated Onyx.get() is synchronous in v2 but asynchronous in v3 (returns Promise). ↓

fix const value = await Onyx.get(KEY);

breaking In v3, Onyx.init requires 'keys' config; previously it was optional. Missing keys causes runtime error. ↓

fix Onyx.init({ keys: { ... } });

Install

npm install react-native-onyx

yarn add react-native-onyx

pnpm add react-native-onyx

Imports

default
wrong
```
const Onyx = require('react-native-onyx')
```
correct
```
import Onyx from 'react-native-onyx'
```
Default import is ESM-only. CJS require will fail due to ESM-first packaging.
useOnyx
```
import { useOnyx } from 'react-native-onyx'
```
Named export for React hook. TypeScript: import { useOnyx } from 'react-native-onyx' works directly.

Onyx.connect

wrong

import { connect } from 'react-native-onyx'

correct

import Onyx from 'react-native-onyx'; Onyx.connect({key: 'foo', callback: ...})

connect is only available as a method on the default import, not a named export.

Quickstart

Shows full Onyx setup: import, init, set, merge, and useOnyx hook in a React component.

import Onyx from 'react-native-onyx';
import { useOnyx } from 'react-native-onyx';

// Define keys
const ONYXKEYS = {
    SESSION: 'session',
    COLLECTION: { REPORT: 'report_' },
};

// Initialization
Onyx.init({ keys: ONYXKEYS });

// Setting data
Onyx.set(ONYXKEYS.SESSION, { token: 'abc123' });

// Merging data
Onyx.merge(ONYXKEYS.SESSION, { email: 'user@example.com' });

// In a React component
function SessionInfo() {
    const [session] = useOnyx(ONYXKEYS.SESSION);
    return <Text>{session?.email}</Text>;
}