expo-storage

A simple and efficient solution for persistent data storage in Expo/React Native applications, designed to overcome the size limitations of react-native async-storage by utilizing the expo-file-system.

Features

• No size limitations (unlike AsyncStorage)
• Simple, Promise-based API
• TypeScript support
• Persistent storage across app restarts
• JSON object support through automatic serialization
• Built-in security features
  • Path traversal prevention
  • Safe filename validation
  • Automatic value serialization
  • Directory existence checks
  • Comprehensive error handling

Requirements

• Expo SDK 18 or newer
• React 18.2.0 or newer
• React Native 0.74.3 or newer
• expo-file-system

Installation

Using yarn:

1yarn add expo-storage

Using expo:

1expo install expo-storage

Usage

Importing

1import { Storage } from 'expo-storage'

API

Store Data

1try {
2  await Storage.setItem({
3    key: "myKey",
4    value: myValue // automatically serialized if not a string
5  })
6} catch (error) {
7  // Handle invalid keys or storage failures
8}

Retrieve Data

1try {
2  const item = await Storage.getItem({ key: "myKey" })
3  if (item !== null) {
4    const parsedItem = JSON.parse(item)
5  }
6} catch (error) {
7  // Handle invalid keys or read failures
8}

Delete Data

1try {
2  await Storage.removeItem({ key: "myKey" })
3} catch (error) {
4  // Handle invalid keys or deletion failures
5}

List All Keys

1try {
2  const keys = await Storage.getAllKeys()
3} catch (error) {
4  // Handle listing failures
5}

Security Features

Key Validation

• Keys must be non-empty strings
• Only alphanumeric characters, hyphens, underscores, and dots are allowed
• Path traversal attempts are blocked
• Invalid keys throw errors

Value Handling

• Automatic serialization of non-string values
• Safe JSON parsing
• Proper error propagation

Storage Directory

• Automatic creation of storage directory if needed
• Safe directory operations
• Path sanitization

Error Handling

All methods may throw errors for:

• Invalid keys (non-alphanumeric or potential path traversal)
• File system operation failures
• Serialization failures for non-string values

Example error handling:

1try {
2  await Storage.setItem({
3    key: "user-preferences",
4    value: { theme: "dark" }
5  })
6} catch (error) {
7  if (error.message.includes('Invalid storage key')) {
8    // Handle invalid key error
9  } else {
10    // Handle other storage errors
11  }
12}

Storage Location

Data is stored in the app's document directory using expo-file-system, ensuring:

• Persistence across app restarts
• No size limitations
• Private storage accessible only to your app
• Safe file operations

Sample Projects

• WiSaw App: GitHub | Website

License

MIT License - See LICENSE file for details

Contributing

Issues and pull requests are welcome at the GitHub repository.