react-native-onyx

library3.0.71jsnpmunverified

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.

database workflow

npm install react-native-onyx

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-ONYX

react-native-onyx

databasejavascriptv3.0.71

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import Onyx from 'react-native-onyx'

✗ const Onyx = require('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

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

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

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

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>; }

Debug

Known issues

breakingVersion 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

affects: >=3.0.0

gotchaObject 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'

affects: >=1.0.0

gotchaOnyx.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);

affects: >=1.0.0

deprecatedOnyx.get() is synchronous in v2 but asynchronous in v3 (returns Promise).

fix

const value = await Onyx.get(KEY);

affects: >=3.0.0

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

fix

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

affects: >=3.0.0

Errors

Common errors & fixes

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

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"

TypeError: Onyx.init is not a function

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'

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

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' })

Onyx.connect callback is not called for existing data

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

Upgrade

Version history

3.0.71latest on npm

Audit

Dependencies

idb-keyvalrequiredIndexedDB key-value store for web/browser fallback

react-native-device-inforequiredDevice information for storage key derivation

react-native-nitro-modulesrequiredNative modules bridge for SQLite backend

react-native-nitro-sqliterequiredSQLite backend for persistent storage on native

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Expensify/react-native-onyx ↗

packagehttps://www.npmjs.com/package/react-native-onyx ↗

homepagehttps://expensify.com ↗