Settings Mount Point

The settings mount point provides a configuration interface that appears in the Studio sidebar when an administrator selects an application instance in a playlist. It allows administrators to customize each placement of the application — choosing a city for a weather widget, selecting a color theme, entering an API key — without touching code. Data saved in the settings view is written to instance storage and propagates to the render view on devices in real time.

Configuration

The settings path is declared in telemetry.config.json:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

The path /settings tells the platform to load the settings entry point when an administrator opens the configuration panel. During the build, your build tool produces an index.html at this path, and that file renders inside the Studio sidebar iframe.

Runtime Context

The settings view runs inside an iframe in the Studio web application at studio.telemetryos.com. It does not run on physical devices. Because there is no device context, the device storage scope is not available. All other SDK functionality works normally.

Instance storage is the default and most commonly used scope in settings. When the same application is placed on two different playlists — one showing weather for New York and another for London — each placement has its own instance storage. The settings view reads and writes to the instance that the administrator currently has selected.

Example

A typical settings component loads existing configuration when it mounts, lets the administrator edit values through a form, and saves changes to instance storage:

import { configure, store } from '@telemetryos/sdk';
import { useState, useEffect } from 'react';

configure();

function SettingsForm() {
  const [city, setCity] = useState('');
  const [units, setUnits] = useState('F');
  const [saved, setSaved] = useState(false);

  // Load existing configuration
  useEffect(() => {
    store().instance.get<{ city: string; units: string }>('config').then((config) => {
      if (config) {
        setCity(config.city);
        setUnits(config.units);
      }
    });
  }, []);

  const handleSave = async () => {
    try {
      await store().instance.set('config', { city, units });
      setSaved(true);
      setTimeout(() => setSaved(false), 2000);
    } catch (error) {
      console.error('Failed to save settings:', error);
    }
  };

  return (
    <form>
      <label>
        City:
        <input value={city} onChange={(e) => setCity(e.target.value)} />
      </label>
      <label>
        Units:
        <select value={units} onChange={(e) => setUnits(e.target.value)}>
          <option value="F">Fahrenheit</option>
          <option value="C">Celsius</option>
        </select>
      </label>
      <button type="button" onClick={handleSave}>
        {saved ? 'Saved!' : 'Save'}
      </button>
    </form>
  );
}

Communication with Render

Settings and render communicate through instance storage. When the settings view writes a value, the render view on the device receives the change through a subscription callback within seconds:

// Settings view writes
await store().instance.set('config', { city: 'New York', units: 'F' });

// Render view subscribes
store().instance.subscribe('config', (newConfig) => {
  updateDisplay(newConfig);
});

This pattern is the backbone of most TelemetryOS applications. The settings view is the input surface, instance storage is the transport, and the render view is the output surface. Changes propagate in real time across the network — no polling, no manual refresh.

Best Practices

Always load and display existing configuration when the settings view mounts. Administrators expect to see what is currently configured so they can make informed changes. An empty form with no indication of current values is confusing and error-prone.

Validate input before saving to storage. Check for empty required fields, malformed URLs, and out-of-range numbers. Provide clear feedback on whether a save succeeded or failed — a brief confirmation message or a color change on the save button is sufficient.

Keep the interface simple and focused. The settings sidebar in Studio has limited width, so design for a narrow viewport. Administrators want quick, straightforward configuration rather than complex multi-step workflows. Group related settings logically and use clear labels.

Use instance storage by default. Most settings are specific to a particular placement of the application (which city to show, which data source to use). Reserve application storage for configuration that genuinely applies to every instance everywhere, such as a company logo URL or a global API endpoint.

Provide sensible defaults. When an administrator places a new application instance in a playlist, the settings view should display reasonable starting values rather than requiring configuration before anything works. The render view should handle the unconfigured state gracefully as well.

Common Use Cases

Settings views are used to configure content sources (API endpoints, RSS feeds, data connections), display preferences (themes, colors, fonts, layouts), location-specific data (city names, branch identifiers, room numbers), refresh intervals and timing controls, credentials and API keys for external services, and content selections from the media library.