Store Data

Key-ValueAuthData Modeling

The foundation of every application is storing data, and in Puter.js you do that with the key-value store API. It supports the standard operations you would expect from any database, such as writes, reads, updates, deletes, and more. All data lives inside the user's own Puter account.

Set

To store data, use the puter.kv.set() method. It takes a key and a value:

await puter.kv.set('theme', 'dark');

A value can be a string, a number, a boolean, or a whole object or array, so a structured record goes in the same way a single setting does:

await puter.kv.set('settings', { theme: 'dark', sound: false, volume: 0.8 });
await puter.kv.set('recent', ['puter.js', 'kv', 'workers']);

Setting the same key again replaces its value:

await puter.kv.set('theme', 'dark');
await puter.kv.set('theme', 'light');   // 'theme' is now 'light'

Get

To read it back, use the puter.kv.get() method. It takes a key and returns the value in the shape you stored it:

const settings = await puter.kv.get('settings');
settings.theme;      // 'dark'

A key that was never written comes back empty, which is where your defaults go:

const settings = await puter.kv.get('settings') ?? { theme: 'light', sound: true };

For most apps that is the whole storage layer. You call puter.kv.set() when something changes and puter.kv.get() when the app loads.

Where the Data Lives

Each entry is written to the signed-in user's own account, inside a sandbox that belongs to your app. User A's settings and user B's settings are separate entries, and neither user can read the other's. Every other app in the same account gets its own sandbox, so your keys and another app's keys never mix. The user covers their own storage under the User-Pays Model.

List

To see what you stored, use the puter.kv.list() method. It returns the keys your app wrote for this user, sorted by key:

const keys = await puter.kv.list();
// ['recent', 'settings', 'theme']

Pass true to get the values along with them:

const entries = await puter.kv.list(true);
// [{ key: 'recent', value: ['puter.js', 'kv', 'workers'] }, ...]

Delete

To remove one entry, use the puter.kv.del() method:

await puter.kv.del('theme');

Flush

To empty your app's sandbox for this user, use the puter.kv.flush() method:

await puter.kv.flush();

Notes

← All recipes