# expo-storage

> Simple way to store persistent data, which does not have size limitations of react-native async-storage.

Latest version **57.0.0** (published 2026-08-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install expo-storage
pnpm add expo-storage
yarn add expo-storage
bun add expo-storage
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 57.0.0 |
| Published | 2026-08-07 |
| First published | 2021-08-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Author | echowaves.com |
| Maintainers | echowaves |
| Keywords | expo, react-native, asynch-storage, persistance |

## Links

- npm: https://www.npmjs.com/package/expo-storage
- Repository: https://github.com/echowaves/expo-storage
- Homepage: https://github.com/echowaves/expo-storage#readme
- Issues: https://github.com/echowaves/expo-storage/issues
- npm.io page: https://npm.io/package/expo-storage

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 57.0.0 (latest) — 2026-08-07
- 55.0.5 — 2026-03-06
- 54.0.9 — 2025-12-09
- 54.0.8 — 2025-11-15
- 54.0.7 — 2025-11-15
- 54.0.6 — 2025-10-14
- 54.0.5 — 2025-10-14
- 54.0.4 — 2025-10-12
- 54.0.2 — 2025-09-14
- 54.0.1 — 2025-09-14
- 54.0.0 — 2025-09-13
- 53.0.11 — 2025-06-09
- 53.0.9 — 2025-05-23
- 52.0.40 — 2025-03-23
- 51.0.8 — 2024-07-04
- … 11 more at https://npm.io/package/expo-storage/versions

## README

# 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 54 or newer
- React 19.0.0 or newer
- React Native 0.81.0 or newer
- expo-file-system 19.0.0 or newer

## Installation

Using yarn:
```bash
yarn add expo-storage
```

Using expo:
```bash
expo install expo-storage
```

## Usage

### Importing

```javascript
import { Storage } from 'expo-storage'
```

### API

#### Store Data

```javascript
try {
  await Storage.setItem({
    key: "myKey",
    value: myValue // automatically serialized if not a string
  })
} catch (error) {
  // Handle invalid keys or storage failures
}
```

#### Retrieve Data

```javascript
try {
  const item = await Storage.getItem({ key: "myKey" })
  if (item !== null) {
    const parsedItem = JSON.parse(item)
  }
} catch (error) {
  // Handle invalid keys or read failures
}
```

#### Delete Data

```javascript
try {
  await Storage.removeItem({ key: "myKey" })
} catch (error) {
  // Handle invalid keys or deletion failures
}
```

#### List All Keys

```javascript
try {
  const keys = await Storage.getAllKeys()
} catch (error) {
  // Handle listing failures
}
```

### 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:
```javascript
try {
  await Storage.setItem({
    key: "user-preferences",
    value: { theme: "dark" }
  })
} catch (error) {
  if (error.message.includes('Invalid storage key')) {
    // Handle invalid key error
  } else {
    // Handle other storage errors
  }
}
```

## 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](https://github.com/echowaves/WiSaw) | [Website](https://www.wisaw.com/)

## License

MIT License - See LICENSE file for details

## Contributing

Issues and pull requests are welcome at the [GitHub repository](https://github.com/echowaves/expo-storage).

<a href="https://app.codacy.com/gh/echowaves/expo-storage/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/d2ae6874e2954c0fbfaca3591bbd7e0c"/></a>

---
_Source: https://npm.io/package/expo-storage · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._