Store Data

Key-ValueAuthData Modeling

Every app needs to save data and load it again. In Puter.js you do that with the key-value store, which covers the writes, reads, updates and deletes you'd expect from a database. Each user's data lives in their 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:

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.

Get

To read a value back, use the puter.kv.get() method. It 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 as null, which is where your defaults go:

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

Update

To change some fields of an object without writing the rest, use the puter.kv.update() method:

await puter.kv.update('settings', { volume: 0.5 });

The other fields stay as they are. Save User Settings covers nested fields, and Add Counters covers numbers that go up and down.

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 your app's keys for this user, sorted by key:

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

Pass true to get the values with them:

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

Once your app stores more than a few hundred keys, list one group at a time, as in Store a Large Collection.

Delete

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

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

To delete everything your app stored for this user, use the puter.kv.flush() method:

await puter.kv.flush();

Notes

← All recipes