expo-storage

library55.0.5jsnpmunverified

A persistent key-value storage library for Expo and React Native apps that removes the size limitations of react-native AsyncStorage by using expo-file-system. Version 55.0.5 requires Expo SDK 54+, React 19+, and expo-file-system 19+. The library provides a simple, Promise-based API with TypeScript support, automatic JSON serialization for non-string values, and built-in security features like key validation and path traversal prevention. It stores data in the app's private document directory, ensuring persistence across restarts without size constraints.

storage

npm install expo-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPO-STORAGE

expo-storage

storagejavascriptv55.0.5

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.

Storage

✓ import { Storage } from 'expo-storage'

✗ import Storage from 'expo-storage'

Named export only; default import is not available and will return undefined.

Storage.setItem

✓ await Storage.setItem({ key: 'k', value: 'v' })

✗ await Storage.setItem('k', 'v')

API expects an object with key and value properties, not positional arguments.

Storage.getItem

✓ const item = await Storage.getItem({ key: 'k' })

✗ const item = await Storage.getItem('k')

Must pass an object with key property; returning null if key not found.

Storage.removeItem

✓ await Storage.removeItem({ key: 'k' })

✗ await Storage.removeItem('k')

Similar to other methods, expects an object with key.

Storage.getAllKeys

✓ const keys = await Storage.getAllKeys()

✗ const keys = await Storage.getAllKeys({})

No arguments needed; returns an array of string keys.

Demonstrates basic CRUD operations: store, retrieve, list keys, and delete data using the object-parameter API.

import { Storage } from 'expo-storage'; async function example() { try { await Storage.setItem({ key: 'user', value: { name: 'Alice', age: 30 } }); const raw = await Storage.getItem({ key: 'user' }); if (raw !== null) { const parsed = JSON.parse(raw); console.log(parsed); // { name: 'Alice', age: 30 } } const keys = await Storage.getAllKeys(); console.log('Stored keys:', keys); await Storage.removeItem({ key: 'user' }); } catch (error) { console.error('Storage error:', error); } } example();

Debug

Known issues

breakingAPI uses object parameters instead of positional arguments

fix

Use { key: 'k', value: 'v' } instead of ('k', 'v') for setItem, getItem, removeItem.

affects: >=1.0.0

deprecatedIn version 55, expo-storage requires expo-file-system 19+ and Expo SDK 54+. Older versions of these dependencies may cause runtime errors.

fix

Update expo-file-system to ^19.0.0 and ensure Expo SDK >= 54.

affects: >=55.0.0

gotchaKeys must only contain alphanumeric characters, hyphens, underscores, and dots. Invalid keys throw an error.

fix

Validate keys with /^[a-zA-Z0-9_.-]+$/ before storing.

affects: >=1.0.0

gotchaValues are automatically serialized to JSON if not a string. When retrieving, you must manually parse the string with JSON.parse.

fix

Call JSON.parse on the result of getItem if you stored a non-string value.

affects: >=1.0.0

breakingNo default export; only named export { Storage } is available.

fix

Use import { Storage } from 'expo-storage' instead of import Storage from 'expo-storage'.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: undefined is not an object (evaluating 'Storage.setItem')

Using default import instead of named import.

fix

Change to: import { Storage } from 'expo-storage'

Invariant Violation: The module 'expo-file-system' is not installed

Missing or incompatible peer dependency expo-file-system.

fix

Run: expo install expo-file-system or ensure version ^19.0.0 is installed.

Error: Invalid storage key: 'path/../traversal'

Key contains invalid characters or path traversal attempt.

fix

Use only alphanumeric, hyphen, underscore, and dot characters. Avoid '../' or '/'. Example: 'user-preferences'

Error: The provided value must be a string or object. Received: number

Passing a primitive number without object wrapper.

fix

Wrap in object: { key: 'k', value: 42 } instead of Storage.setItem({ key: 'k', value: 42 }) is actually correct. If error persists, check value is not undefined.

Upgrade

Version history

55.0.5latest on npm

Audit

Dependencies

expo-file-systemrequiredRequired peer dependency for file-based storage operations

Agent activity

28 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/echowaves/expo-storage ↗

packageexpo-storage ↗

homepagehttps://github.com/echowaves/expo-storage#readme ↗