Skip to content

index.md

Latest commit

 

History

History
92 lines (63 loc) · 4.26 KB

index.md

File metadata and controls

92 lines (63 loc) · 4.26 KB
Raw
name Key-Value Storage
SPDX-FileCopyrightText Copyright (c) 2026 Moddable Tech, Inc.
updated 2026-08-04

Key-value storage lets a project store small pieces of data, such as settings and state, that persist across restarts. The Moddable SDK provides two APIs: the high-level web standard Web Storage API (localStorage), and the low-level ECMA-419 embedded standard Key-Value store. Both organize data into named domains, each holding a set of key-value pairs. In fact, Web Storage is implemented using the Key-Value store.

Key-Value store replaces the Moddable SDK's Preferences module. The names are quite different, so this is easy to miss.

Using Web Storage

Using ECMA-419 Key-Value Store

How to Choose

If Web Storage works for your project, you should use it. Because localStorage is a well-known web standard, many developers are already familiar with it, and it requires the least code. Web Storage values are always strings, so binary and structured data must be encoded, for example as Base64 or JSON.

The Key-Value store is a better choice when you work directly with binary data. It reads and writes Byte Buffers by default and supports several numeric and string data formats. It also has lower runtime overhead and lets you iterate a domain's keys directly.

Setting Up Web Storage

To access key-value pairs using Web Storage, a Web Storage instance must first be bound to a Key-Value store domain. Because localStorage is commonly used on the Web, this example binds the domain "local" to the global variable localStorage. You can create several instances of Web Storage, for example, a sessionStorage for Web compatibility.

import WebStorage from "webstorage";

const kvp = device.keyValue.open({
	path: "local"
});
globalThis.localStorage = new WebStorage(kvp);

When building with mcpack or developing for Alloy on Pebble OS, this step is unnecessary as both create localStorage for you.

Building with mcconfig

Include the Web Storage manifest in your project's manifest.json. It includes the Key-Value store, so no other manifest is needed:

$(MODDABLE)/examples/io/storage/webstorage/manifest_webstorage.json

Then, import the module in your JavaScript source code:

import WebStorage from "webstorage";

To use the Key-Value store directly, include its manifest:

$(MODDABLE)/modules/io/storage/manifest.json

Then, import the module in your JavaScript source code:

import keyValue from "embedded:storage/key-value";

Building with mcpack

When building with mcpack, the Web Storage manifest is included automatically when your project uses the localStorage global. If your project uses webstorage with an import statement, it's manifest is automatically included.

To use the Key-Value store directly, import the module in your JavaScript source code. mcpack automatically includes the manifest.

import keyValue from "embedded:storage/key-value";

Learn More