Development

Tools and guides for developing TelemetryOS applications.

Application Architecture

TelemetryOS applications consist of up to four components:

1. Render Mount Point (/render) - Content displayed on devices
2. Settings Mount Point (/settings) - Configuration UI in admin portal
3. Background Workers - Scripts that run continuously
4. Containers - Docker containers for backend services

All components communicate through the SDK's storage and messaging methods.

Learn more about Mount Points →

Key Concepts

Storage Scopes

• application - Shared across all instances of your application
• instance - Specific to current application instance
• device - Only on current physical device
• shared(namespace) - Inter-application communication

Communication Pattern

Applications run in iframes and communicate with the TelemetryOS platform using the postMessage API. The SDK handles all message formatting, validation, and response handling.

Request Timeout

All SDK requests have a 30-second timeout. Always implement proper error handling.

Local Development

The TelemetryOS CLI provides a local development server that simulates the platform environment. Build and test applications without deploying to the cloud.

Key Features:

• Mock SDK responses for all APIs
• Test mount points in browser
• Hot reload and fast iteration
• Simulated storage with localStorage

View Local Development Guide

AI-Assisted Development with Claude Code

Accelerate your development workflow with Claude Code, Anthropic's free AI coding assistant. With proper configuration using a CLAUDE.md file, Claude Code becomes an expert team member that understands TelemetryOS patterns and helps you build faster.

Benefits:

• 10x faster component scaffolding
• Real-time best practices guidance
• Context-aware code generation
• Instant debugging assistance
• Comprehensive CLAUDE.md template included

View AI-Assisted Development Guide

Understanding CORS

Cross-Origin Resource Sharing (CORS) is a critical browser security mechanism that affects how your applications fetch external data.

Learn About:

• What CORS is and why it matters
• Common CORS errors and solutions
• Using the Proxy API to bypass CORS
• Best practices for external API integration

View CORS Documentation

Code Examples

Complete working examples demonstrating common patterns and best practices.

Included Examples:

• Weather widget with settings and render
• Media slideshow application
• Interactive kiosk with touch support
• Real-time data dashboard
• Multi-instance coordination

View Code Examples

Quick Start Development Flow

1. Install CLI

npm install -g @telemetryos/cli

2. Create Application

tos init my-app
cd my-app
npm install

3. Start Development Server

tos serve

4. Test Mount Points

• Settings: http://localhost:3000/settings
• Render: http://localhost:3000/render

5. Build and Deploy

npm run build
# Then deploy via GitHub integration or zip upload

Development Best Practices

Use TypeScript

All SDK APIs include full TypeScript definitions for type safety and better developer experience.

import { configure, store, type MediaContent } from '@telemetryos/sdk';

Implement Error Handling

All SDK operations can throw errors or timeout. Always implement proper error handling.

try {
  await store().instance.set('key', 'value');
} catch (error) {
  console.error('Failed to save:', error);
  showUserFeedback('Unable to save settings');
}

Test Offline Behavior

Applications should work gracefully when network is unavailable.

try {
  const data = await fetchFromAPI();
  displayData(data);
} catch (error) {
  const cachedData = await store().device.get('cachedData');
  if (cachedData) {
    displayData(cachedData);
  } else {
    showOfflineMessage();
  }
}

Subscribe to Data Changes

Use subscriptions instead of polling for real-time updates.

// ✅ Good - reactive updates
store().instance.subscribe('config', (newConfig) => {
  updateDisplay(newConfig);
});

// ❌ Bad - polling
setInterval(async () => {
  const config = await store().instance.get('config');
  updateDisplay(config);
}, 1000);

Debugging Tips

Enable Console Logging

Use browser DevTools to monitor SDK operations:

console.log('Loading settings...');
const settings = await store().instance.get('settings');
console.log('Settings loaded:', settings);

Test Different Screen Sizes

Applications run on various device types. Test responsive behavior:

// Detect screen size
const isLargeScreen = window.innerWidth > 1920;
const isTouchDevice = 'ontouchstart' in window;

Simulate Network Failures

Test error handling by simulating failures:

// Wrap API calls with timeout simulation
const fetchWithTimeout = async (url: string, timeout = 5000) => {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const response = await fetch(url, { signal: controller.signal });
    return response;
  } finally {
    clearTimeout(timeoutId);
  }
};

Common Development Issues

SDK Not Configured

Error: "SDK not configured"

Solution: Call configure() before using SDK functions

import { configure } from '@telemetryos/sdk';
configure('my-app-name'); // Must match telemetry.config.json

CORS Errors

Error: "blocked by CORS policy"

Solution: Use Proxy API for external requests

import { proxy } from '@telemetryos/sdk';
const response = await proxy().fetch('https://api.example.com/data');

Storage Not Persisting

Error: Data doesn't persist between sessions

Solution: Verify correct storage scope

// Use application or instance scope, not device (in settings)
await store().instance.set('key', 'value'); // ✅ Works in settings
await store().device.set('key', 'value');   // ❌ Not available in settings

Development Workflow

Iterative Development

1. Make code changes
2. Browser auto-reloads (via Vite/webpack)
3. Test in mount points
4. Refine and repeat

Testing

• Test both settings and render mount points
• Verify storage communication between views
• Test with and without configuration
• Simulate different screen sizes

Deployment

• Push to GitHub (recommended)
• Platform automatically builds
• Monitor build logs
• Test on actual devices

Resources

• Local Development - Complete CLI and development server guide
• CORS - Understanding and solving CORS issues
• Code Examples - Working application examples
• SDK Method Reference - Complete SDK method documentation

Next Steps

1. Set up local development - Install CLI and create first app
2. Learn about CORS - Understand external API integration
3. Explore examples - See complete working applications
4. Read SDK docs - Deep dive into SDK capabilities