Storage API

The Storage API provides simple key-value storage scoped to your resource. Each resource has its own isolated namespace — you cannot read or write another resource’s storage.

Capability required: storage:kv

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// Set a value
await rp.storage.set("api_endpoint", "https://api.example.com");

// Get a value
const endpoint = await rp.storage.get("api_endpoint");
// → "https://api.example.com"

// Get a non-existent key
const missing = await rp.storage.get("not_here");
// → null

// List keys by prefix
await rp.storage.set("cache:page1", "...");
await rp.storage.set("cache:page2", "...");
await rp.storage.set("setting:theme", "dark");

const cacheKeys = await rp.storage.list("cache:");
// → ["cache:page1", "cache:page2"]

// Delete a key
await rp.storage.delete("cache:page1");

Backend (Node.js)

The same API is available in backend methods via the rp host object:

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    saveSettings: async (params, { rp }) => {
      await rp.storage.set("settings", JSON.stringify(params));
      return { ok: true };
    },
    
    loadSettings: async (_params, { rp }) => {
      const raw = await rp.storage.get("settings");
      return raw ? JSON.parse(raw) : {};
    },
  },
});

server.start();

API Reference

rp.storage.get(key)

Parameter	Type	Description
key	string	The key to retrieve
Returns	Promise<string | null>	The value, or null if not found

rp.storage.set(key, value)

Parameter	Type	Description
key	string	The key to store
value	string	The value to store
Returns	Promise<void>

rp.storage.delete(key)

Parameter	Type	Description
key	string	The key to delete
Returns	Promise<void>

rp.storage.list(prefix?)

Parameter	Type	Description
prefix	string (optional)	Filter keys by prefix
Returns	Promise<string[]>	Array of matching key names

Manifest Configuration

{
  "capabilities": [
    "storage:kv"
  ]
}

Notes

• Values are strings only. To store objects, use JSON.stringify() / JSON.parse().
• Storage persists across app restarts and resource updates.
• Storage is deleted when the resource is uninstalled.
• There is no size limit per key, but keep values reasonable (under 1MB).