Integration guides

Feature state

Choose how Feature application state is stored, isolated, and synchronized.

AI generated The content on this page was written using large language models.

A Feature can save JSON application state while it runs. Your integration chooses where that state lives and who shares it.

For the interface contract, see RoughFrameDatastore.

Application state is not metadata

Rough synchronizes Feature metadata, such as its name and published build. The client keeps a separate metadata cache for each Project, user, and account.

Feature application state is the JSON data the Feature saves while it runs. It has its own persistence mechanism. It is also separate from application data read or changed through your capabilities.

Choosing an account ID for shared Features does not automatically give their application state shared storage across browsers.

Understand the default storage

By default, application state is stored in the host browser's local storage, keyed only by Feature ID.

Default state is not isolated by user or account. People opening the same Feature on the same browser origin share that stored state, even after switching users. Creating a new client does not change this behavior.

The default is local to that browser and origin. Do not rely on it for cross-browser persistence or user/account isolation.

Choose your state scope

Pass a custom datastore to mountRoughFeature() when you need different behavior. Decide who should share state before choosing storage:

Requirement Scope and storage approach
Temporary state for one mounted Feature Create a separate in-memory store for that Feature and identity.
Private state per user Key persistent state by Project, account, user, and Feature.
Shared state within an account Key persistent state by Project, account, and Feature; use a backend if it must work across browsers.

These are design choices for your datastore, not built-in SDK modes. Storage keys alone are not authorization: your backend must verify access to remotely stored state.

Implement a datastore

The interface has three methods:

  • get() returns the current JSON state synchronously, or undefined if there is none.
  • set(state) saves the new state and notifies registered listeners.
  • addListener(callback) registers a listener and returns a function that removes it. Notify listeners about changes received from other viewers too.

Keep the same datastore object while the Feature is mounted. Update its state through set() and listener notifications instead of replacing the object on every render.

Example: isolated, temporary state

This factory creates a separate in-memory store for each call. It does not persist across reloads or synchronize browsers. Create a fresh store per Feature and identity rather than reusing a global one.

import type { JsonValue, RoughFrameDatastore } from '@roughapp/feature'

function createMemoryDatastore(): RoughFrameDatastore {
  let state: JsonValue | undefined
  const listeners = new Set<(state: JsonValue) => void>()
  return {
    get: () => state,
    set(next) {
      state = next
      for (const listener of listeners) listener(next)
    },
    addListener(callback) {
      listeners.add(callback)
      return () => {
        listeners.delete(callback)
      }
    },
  }
}

Pass the store when mounting. Here, client and surface are your existing integration objects, and feature is an item from your published-Feature list. Add an element with id="feature-slot" to your page.

import { mountRoughFeature } from '@roughapp/feature'

const container = document.querySelector<HTMLElement>('#feature-slot')!
const datastore = createMemoryDatastore()
const mount = mountRoughFeature(container, {
  client,
  surface,
  featureId: feature.id,
  datastore,
})

// Register with your view's teardown; do not call immediately.
function cleanupFeature() {
  mount.unmount()
  container.remove()
}

When switching users or accounts, tear down the old integration and create stores with the new identity's scope. A new client alone does not reset a reused store.

Connect remote persistence

A remote datastore still needs a synchronous get(). A typical implementation:

  1. Loads initial state before mounting, or maintains a local snapshot that get() can read immediately.
  2. Updates that snapshot and notifies listeners when set() is called.
  3. Persists changes to an authorized backend.
  4. Receives remote updates, updates the snapshot, and notifies listeners without writing the same update back in a loop.
  5. Removes remote listeners when they are no longer needed.

If several viewers can write at once, your persistence layer must define how conflicting or out-of-order updates are handled. The datastore interface does not provide a conflict-resolution policy.

Handle persistence failures inside your datastore. The SDK does not await the promise returned by set(). Catch asynchronous failures there and decide how your app retries, reports an unsaved change, or restores the last saved state. The client's authentication onError does not handle these failures.

The in-memory example above is only an interface example, not a production remote-storage implementation. See the SDK Reference for exact method signatures and the JsonValue type.