Storage API for Node, React Native, and the browser

Stashy uses the best storage backend for each environment.

Live demo project for web

Getting started

Install the package:

npm install @waveplay/stashy

Use functions such as get(key) or set(key, value). These will be delegated to the correct backend based on the environment your code is running in.

import stashy from '@waveplay/stashy'

// Get a value from storage
const displayName = stashy.getString('name')
console.log(`Your username is ${displayName}`)

// Update a value in storage
// It'll be saved and available when you come back later
stashy.set('name', 'Pkmmte Xeleon')

See the sample project for more usage examples.

API reference

| Function | Description | | ----------------- | -------------------------------------------------------- | | clearAll | Clears all data from the backend. | | delete | Deletes the value for the given key. | | get | Gets the value for the given key. | | getAsync | Gets the value for the given key asynchronously. | | getBoolean | Gets the boolean value for the given key. | | getBooleanAsync | Gets the boolean value for the given key asynchronously. | | getNumber | Gets the number value for the given key. | | getNumberAsync | Gets the number value for the given key asynchronously. | | getString | Gets the string value for the given key. | | getStringAsync | Gets the string value for the given key asynchronously. | | set | Sets the value for the given key. |

Default instance

When you use import stashy from '@waveplay/stashy', you're importing the default instance of Stashy. This instance is created with the default options and will use the best backend for your environment.

This may be considered unnecessary overhead if you're creating new instances of Stashy in your code instead of using the default instance. Import from @waveplay/stashy/core instead to avoid this overhead.

import { Stashy } from '@waveplay/stashy/core'

const stashy = new Stashy({
	// ... your custom options
})

Backends

Stashy comes with a few backends available out of the box. You can also create your own backend by implementing the StashyBackend interface.

import { Stashy } from '@waveplay/stashy'
import { StashyBackend } from '@waveplay/stashy/backend'

class CustomBackend implements StashyBackend {
	// ... your custom backend implementation
}

const stashy = new Stashy({
	backend: new CustomBackend()
})

// or with different backends per environment
const stashy = new Stashy({
	backend: {
		native: new MmkvBackend(),
		ssr: new CookieBackend(),
		web: new CustomBackend()
	}
})

AsyncStorage

This backend uses @react-native-async-storage/async-storage to store data. It is the default backend for native and only works with async functions such as getStringAsync().

import { AsyncStorageBackend } from '@waveplay/stashy/backend/async-storage'

Cookie

Cookie-backed storage perfect for server-side environments. It is the default backend for SSR and requires a context object to be passed with every function call.

import { CookieBackend } from '@waveplay/stashy/backend/cookie'

Env

Meant to use process.env variables. Supports dot notation for nested objects.

import { EnvBackend } from '@waveplay/stashy/backend/env'

Note: This will not load the .env file for you. Use with dotenv if you need to load the .env file. Frameworks like Next.js and Pilot.js do this automatically.

LocalStorage

Relies on localStorage to store data. It is the default backend for web.

import { LocalStorageBackend } from '@waveplay/stashy/backend/local-storage'

MMKV

Extremely fast and efficient storage for React Native, but requires that you install react-native-mmkv separately. If you're using Expo, you will also need to generate a new development client build.

import { MmkvBackend } from '@waveplay/stashy/backend/mmkv'

Debugging

You can pass your own logger (such as pino) to Stashy when creating a new instance and it will be used to log events. This is useful for debugging backend and environment issues.

The id property is included in each log message to help you differentiate between multiple instances of Stashy.

import { Stashy } from '@waveplay/stashy'
import pino from 'pino'

const stashy = new Stashy({
	id: 'my-stash',
	logger: pino({ level: 'debug' })
})

Credits

This project was originally developed for WavePlay.

License

The MIT License.