Stashy

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

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.