Guides
Start typing to search…

Local Development

Develop and test TelemetryOS applications locally before deployment using the TelemetryOS CLI development server.

Local Development

Develop and test TelemetryOS applications locally before deployment.

Overview

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

CLI Tool

Installation

npm install -g @telemetryos/cli

Or use locally in your project:

npm install --save-dev @telemetryos/cli

Available Commands

tos init

Scaffold a new application from template.

tos init my-application

What it does:

  • Creates project directory
  • Sets up Vite + React + TypeScript template
  • Creates telemetry.config.json
  • Installs dependencies
  • Initializes git repository

Options:

  • --template <name> - Use specific template (default: vite-react-typescript)

tos serve

Start local development server.

tos serve

What it does:

  • Reads telemetry.config.json
  • Runs your devServer.runCommand (e.g., vite --port 3000)
  • Provides development host UI
  • Simulates TelemetryOS SDK environment

Configuration:

In telemetry.config.json:

{
  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}

Development Workflow

1. Create Application

tos init weather-widget
cd weather-widget

2. Install Dependencies

npm install

3. Start Development

tos serve

Or use npm script:

npm run dev

4. Access Mount Points

Navigate to your configured mount points:

5. Make Changes

Edit files in src/ directory. Hot module replacement (HMR) reloads changes automatically.

6. Test Functionality

Test SDK features using mock responses:

  • Storage APIs work with localStorage
  • All SDK methods return simulated responses
  • State persists across page reloads

Development Host UI

The development host UI provides a simulated TelemetryOS environment for testing applications.

Features

  • Canvas Display - Simulates device screen
  • Settings Panel - Simulates admin settings sidebar
  • Scaling Container - Responsive scaling for different screen sizes
  • SDK Bridge - Mock SDK responses for local development
  • Local Storage - Persistent storage simulation

Using the Host UI

tos serve

Access at configured URL (typically http://localhost:3000).

Interface Components:

  • Canvas - Displays render mount point
  • Sidebar - Displays settings mount point
  • Controls - Scale, theme, responsive testing

Mock SDK Behavior

During local development, SDK methods return mock data:

Storage

// Works locally using localStorage
await store().instance.set('key', 'value');
const value = await store().instance.get('key');

// Subscriptions work with localStorage events
store().instance.subscribe('key', (value) => {
  console.log('Value changed:', value);
});

Media

// Returns sample media data
const media = await media().getAllByTag('featured');
// media contains mock MediaContent objects

Playlist & Overrides

// Operations succeed but don't affect actual playback
await playlist().nextPage(); // Returns true
await overrides().setOverride('alert'); // Returns true

Accounts & Users

// Returns mock account and user data
const account = await accounts().getCurrent();
// account = { id: 'mock-account-id' }

Testing Patterns

Manual Testing

Settings Mount Point:

  1. Navigate to /settings
  2. Configure application settings
  3. Save to storage
  4. Verify UI updates

Render Mount Point:

  1. Navigate to /render
  2. Verify subscription to settings
  3. Check display updates when settings change
  4. Test all display states

Browser DevTools

Use Chrome/Firefox DevTools for debugging:

Console:

// Access SDK directly in console
telemetry.store().instance.get('key')
telemetry.playlist().nextPage()

Application Tab:

  • View localStorage (storage simulation)
  • Inspect session storage
  • Check service workers

Network Tab:

  • Monitor external API calls
  • Check proxy requests
  • Verify resource loading

React DevTools

Install React DevTools extension:

  • Inspect component tree
  • View props and state
  • Profile performance
  • Debug hooks

Common Development Issues

SDK Not Configured Error

Error: SDK is not configured

Fix: Call configure() before using SDK methods:

import { configure } from '@telemetryos/sdk';

configure('my-app-name'); // Must match telemetry.config.json

Mount Point Not Loading

Error: 404 or blank page

Fix: Check routing in App.tsx:

const path = window.location.pathname;

if (path === '/settings') return <Settings />;
if (path === '/render') return <Render />;

Hot Reload Not Working

Issue: Changes don't appear automatically

Fixes:

  • Restart dev server (tos serve)
  • Check Vite config for HMR settings
  • Clear browser cache
  • Check for TypeScript errors

Storage Not Persisting

Issue: Data clears on refresh

Cause: Using wrong storage scope

Fix: Use instance or application scope:

// ✅ Persists across reloads
await store().instance.set('key', 'value');

// ❌ May not persist in dev environment
await store().device.set('key', 'value');

Building for Production

Build Command

npm run build

Creates production files in dist/ directory.

Build Output

dist/
├── index.html
├── assets/
│   ├── index-abc123.js
│   └── index-def456.css
└── telemetry.config.json

Important: telemetry.config.json must be in build output.

Verify Build

Check that build contains:

  • ✅ All HTML files
  • ✅ All assets (JS, CSS, images)
  • ✅ telemetry.config.json at root
  • ✅ Correct mount point paths

Deployment to TelemetryOS

TelemetryOS provides three deployment methods. GitHub integration is strongly recommended for automatic builds and seamless updates.

Method 1: GitHub Integration (Recommended)

The preferred deployment method with automatic building and updates.

Workflow:

  1. Create GitHub Repository

    git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-org/your-app.git
git push -u origin main

  2. Connect in Studio

    • Log in to TelemetryOS Studio (studio.telemetryos.com)
    • Navigate to Applications section
    • Click "New Application"
    • Select "GitHub Integration"
    • Connect your GitHub repository
    • Select branch to watch (e.g., main)

  3. Automatic Building

    • TelemetryOS watches for changes via GitHub webhooks
    • On push, builds application in container
    • Deploys to TelemetryOS infrastructure
    • URL and hosting managed transparently

  4. Use in Playlists

    • Add application to playlists
    • Position as region on page (or full screen)
    • Configure using settings mount point
    • Assign to devices

Benefits:

  • ✅ Automatic updates on every push
  • ✅ GitHub Actions integration
  • ✅ Version history and rollback
  • ✅ Collaborative development workflow
  • ✅ No manual build steps

Method 2: Zip File Upload

Upload a pre-built application archive directly.

Workflow:

  1. Build Your Application

    npm run build
cd dist
zip -r ../my-app.zip .

  2. Upload to Studio

    • Navigate to Applications section
    • Click "New Application"
    • Select "Upload Archive"
    • Upload your zip file
    • Platform extracts and validates

  3. Manual Updates

    • Build locally
    • Create new zip
    • Upload to replace previous version

When to Use:

  • Quick prototypes or testing
  • No access to GitHub
  • One-time or infrequent updates

Limitations:

  • ❌ No automatic updates
  • ❌ Manual build and upload process
  • ❌ No version history
  • ❌ No collaborative workflow

Method 3: Generic Git Repository

Connect any Git repository (GitLab, Bitbucket, self-hosted).

Workflow:

  1. Configure Git Repository

    • Push code to your Git hosting service
    • Get repository URL (HTTPS or SSH)
    • Generate deploy key if using SSH

  2. Connect in Studio

    • Navigate to Applications section
    • Click "New Application"
    • Select "Generic Git Repository"
    • Enter repository URL
    • Add deploy key if needed
    • Select branch to watch

  3. Webhook Setup (Optional)

    • Configure webhook on your Git host
    • Points to TelemetryOS webhook endpoint
    • Triggers builds on push

When to Use:

  • Using GitLab, Bitbucket, or self-hosted Git
  • GitHub not available in your organization
  • Need flexibility with Git hosting

Benefits:

  • ✅ Similar to GitHub integration
  • ✅ Automatic builds (with webhooks)
  • ✅ Version control workflow

Setup Required:

  • Deploy keys for private repositories
  • Webhook configuration for automatic builds

Deployment Method Comparison

FeatureGitHubZip UploadGeneric Git
Automatic Updates✅ Yes❌ No✅ With webhooks
Build Automation✅ Yes❌ Manual✅ Yes
Version History✅ GitHub❌ No✅ Git
Setup Complexity🟢 Easy🟢 Easy🟡 Medium
Collaboration✅ Yes❌ No✅ Yes
Rollback✅ Easy❌ Manual✅ Easy

Recommendation

Use GitHub integration unless you have specific requirements:

  • Seamless developer experience
  • Automatic builds on every push
  • Native GitHub Actions support
  • Easy collaboration and code review
  • Simple rollback to previous versions

Use Zip Upload only for:

  • Quick testing or prototypes
  • One-time deployments
  • Situations without Git access

Use Generic Git when:

  • Organization uses GitLab/Bitbucket
  • GitHub is not available
  • Self-hosted Git is required

Build Configuration

TelemetryOS reads your telemetry.config.json and uses standard build commands:

{
  "name": "my-app",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

Build Process:

  1. Clones repository
  2. Installs dependencies (npm install)
  3. Runs build command (npm run build)
  4. Validates output
  5. Deploys to CDN
  6. Makes available in Studio

Accessing Settings

Once deployed, settings mount point is accessible:

  1. Open playlist in Studio
  2. Click on your application region
  3. Settings sidebar opens automatically
  4. Shows your /settings mount point

Application URLs

TelemetryOS manages all URLs transparently:

  • No need to configure domains
  • No need to manage SSL certificates
  • Automatic CDN distribution
  • Globally distributed hosting

Debugging Production

Browser Console

Applications run in iframes on devices. Use remote debugging:

Android:

  • Enable USB debugging
  • Connect via Chrome DevTools
  • Inspect iframe

Desktop Players:

  • Access local debugging interface
  • View console logs
  • Inspect network requests

Platform Logs

View logs in TelemetryOS Studio:

  • Application build logs
  • Runtime error logs
  • Device console logs

Best Practices

1. Test Locally First

# Always test before committing
tos serve
# Test all mount points
# Verify functionality
# Check for errors

2. Version Control

# Commit working changes
git add .
git commit -m "Add weather display feature"
git push origin main

3. Environment Variables

Use environment variables for configuration:

// vite supports import.meta.env
const API_KEY = import.meta.env.VITE_API_KEY;

.env.local:

VITE_API_KEY=your-api-key-here

4. Test Different Scenarios

  • Configure settings, then view render
  • Test with no configuration
  • Test error states
  • Test loading states
  • Test different data combinations

5. Performance Testing

// Monitor performance
console.time('data-fetch');
const data = await fetchData();
console.timeEnd('data-fetch');

Tips

  1. Use HMR - Saves time during development
  2. Check browser console - Catch errors early
  3. Test both mount points - Settings and render work together
  4. Use TypeScript - Catch errors before runtime
  5. Test on target resolution - Use responsive mode in DevTools

Next Steps

Updated 5 days ago

What’s Next