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.

• Read and Write Values
• Delete Keys
• Enumerate Keys

• Read and Write Values
• Change Data Formats
• Delete Keys
• Enumerate Keys

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.

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.

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";

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";

• Documentation
  • Web Storage API on MDN
  • class Preference in Moddable SDK — the module replaced by the Key-Value store
• Standards
  • Web storage in the WHATWG HTML Standard
  • Key-Value store in ECMA-419
• Example
  • Web Storage example in Moddable SDK
• Implementations
  • Web Storage in Moddable SDK
  • Key-Value store in Moddable SDK
• TypeScript Declarations
  • Web Storage in Moddable SDK
  • Key-Value store in Moddable SDK