Guides
Start typing to search…

Languages Supported

Browser-based execution environment with full web standard support

Languages Supported

TelemetryOS applications run in a modern Chrome browser environment, providing access to the full range of web technologies and standards. Applications execute within an iframe sandbox, providing both security isolation and complete access to browser APIs.

Execution Environment

Chrome Browser Runtime

TelemetryOS devices run a version-controlled Chrome browser managed by the platform. This ensures:

  • Consistent behavior across all devices in the fleet
  • Modern web standards with up-to-date ECMAScript, CSS, and HTML support
  • Predictable APIs without cross-browser compatibility concerns
  • Automatic updates managed by TelemetryOS (no manual browser updates needed)

Applications don't need to worry about browser compatibility—the target is always a known, modern Chrome version.

Iframe Execution

The application's render mount point executes within an iframe embedded in the TelemetryOS player:

TelemetryOS Player (Chrome)
  └─ iframe: https://mystore-kiosk.netlify.app/render
       └─ Application Code (HTML/CSS/JS)

What this means:

  • Isolated execution context - The application runs in its own DOM environment
  • Security sandbox - Standard iframe security restrictions apply
  • postMessage communication - SDK uses postMessage API for platform communication
  • Full browser APIs available - DOM manipulation, Canvas, WebGL, Media APIs, etc.

The iframe approach provides security while maintaining full access to browser capabilities applications need.

Supported Technologies

Core Languages

JavaScript / ECMAScript

  • Modern JavaScript (ES2020+) with async/await, modules, classes
  • TypeScript compiles to JavaScript (recommended for type safety)
  • WebAssembly for performance-critical code

HTML5

  • Semantic HTML with full DOM API access
  • Canvas, SVG for graphics and visualization
  • Video and Audio elements for media playback
  • Web Components for reusable elements

CSS3

  • Modern layout (Flexbox, Grid)
  • Animations and transitions
  • Custom properties (CSS variables)
  • Media queries for responsive design

JavaScript Frameworks

React (Recommended)

We recommend React for TelemetryOS applications:

  • Well-tested with the platform
  • Excellent ecosystem and tooling
  • Component-based architecture fits application structure
  • CLI tool generates React projects by default
import React, { useState, useEffect } from 'react';
import { configure, store } from '@telemetryos/sdk';

function WeatherApp() {
  const [city, setCity] = useState('');

  useEffect(() => {
    configure('weather-app');
    store().instance.subscribe('city', setCity);
  }, []);

  return <div>Weather for {city}</div>;
}

Other Frameworks Supported

Any JavaScript framework that runs in a browser works with TelemetryOS:

  • Vue.js - Progressive framework with reactive data binding
  • Svelte - Compiled framework with minimal runtime
  • Angular - Full-featured framework with TypeScript
  • Preact - Lightweight React alternative
  • Lit - Web Components library
  • Vanilla JavaScript - No framework required

The only requirement: the framework must produce standard HTML/CSS/JS that runs in Chrome.

Build Tools and Bundlers

Vite (Recommended)

  • Fast development server with hot module replacement
  • Optimized production builds
  • First-class TypeScript support
  • Default in CLI-generated applications

Other Tools Supported

  • Webpack - Mature bundler with extensive plugin ecosystem
  • Parcel - Zero-config bundler
  • Rollup - Module bundler for libraries
  • esbuild - Extremely fast bundler
  • Turbopack - Next-gen bundler

Choose based on team preferences—TelemetryOS builds whatever is committed to the repository.

Browser API Access

Applications have full access to standard browser APIs:

Graphics and Rendering

  • Canvas 2D/WebGL - Hardware-accelerated graphics
  • SVG - Vector graphics with DOM manipulation
  • CSS Animations - Performant UI animations
  • WebGL 2.0 - Advanced 3D graphics

Media and Input

  • Media Capture API - Camera and microphone access (via SDK)
  • Touch Events - Multi-touch gestures
  • Pointer Events - Unified mouse/touch/pen handling
  • Web Audio API - Audio processing and synthesis

Data and Storage

  • IndexedDB - Client-side database storage
  • LocalStorage - Simple key-value storage
  • Session Storage - Per-session data
  • Cache API - Service worker caching

Network

  • Fetch API - HTTP requests to external APIs
  • WebSocket - Real-time bidirectional communication
  • Server-Sent Events - Server-to-client push
  • WebRTC - Peer-to-peer communication (limited)

Performance

  • Web Workers - Background JavaScript threads
  • Service Workers - Offline caching and background sync
  • Performance API - Timing and profiling
  • Intersection Observer - Efficient element visibility detection

What's NOT Supported

Server-Side Execution

TelemetryOS applications run client-side only in the browser. There is no server-side rendering or Node.js runtime:

❌ Not Available:

  • Server-side rendering (SSR) frameworks like Next.js with SSR
  • Node.js APIs (fs, path, process, etc.)
  • Server-only npm packages
  • Direct database connections

✅ Use Instead:

  • Client-side rendering (CSR)
  • Browser APIs
  • SDK storage scopes
  • REST/GraphQL API calls to external services
  • Containers for server-side services (runs Docker on device)

Native Mobile APIs

The Chrome environment doesn't provide native mobile APIs:

❌ Not Available:

  • iOS/Android native APIs
  • Native push notifications
  • App Store features
  • Native camera APIs (use SDK camera API instead)

Restricted Browser Features

Some browser features have security restrictions:

❌ Limited/Restricted:

  • Clipboard access (requires user gesture)
  • Fullscreen API (device is already fullscreen)
  • Browser plugins/extensions
  • Chrome-specific APIs not in web standards

Language Patterns

TypeScript (Recommended)

TypeScript provides type safety and better developer experience:

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

interface WeatherConfig {
  city: string;
  units: 'metric' | 'imperial';
}

async function loadConfig(): Promise<WeatherConfig> {
  const city = await store().instance.get<string>('city');
  const units = await store().instance.get<'metric' | 'imperial'>('units');
  return { city, units };
}

Benefits:

  • Catch errors at compile time
  • Full SDK type definitions included
  • Better IDE autocomplete
  • Refactoring confidence

Modern JavaScript

Use modern JavaScript features supported in Chrome:

// Async/await for asynchronous operations
const data = await fetch('https://jsonplaceholder.typicode.com/posts/1').then(r => r.json());

// Destructuring
const { city, temperature } = await loadWeatherData();

// Optional chaining
const temp = weatherData?.current?.temperature ?? 'N/A';

// Modules
import { helper } from './utils.js';
export const processor = (data) => { /*...*/ };

CSS Modules and Preprocessors

Style applications with modern CSS tools:

CSS Modules

import styles from './App.module.css';

function App() {
  return <div className={styles.container}>...</div>;
}

Sass/SCSS

$primary-color: #007bff;

.container {
  background: $primary-color;

  &:hover {
    opacity: 0.9;
  }
}

Tailwind CSS

function Card() {
  return (
    <div className="bg-white rounded-lg shadow-lg p-6">
      <h2 className="text-2xl font-bold">Title</h2>
    </div>
  );
}

Libraries and Dependencies

JavaScript Libraries

Any npm package that works in a browser is supported:

Data Visualization

  • D3.js - Data-driven visualizations
  • Chart.js - Simple charts
  • Plotly - Interactive graphs
  • Three.js - 3D graphics

UI Components

  • Material-UI - React components
  • Ant Design - Enterprise UI
  • Chakra UI - Accessible components
  • shadcn/ui - Tailwind components

Utilities

  • Lodash - Utility functions
  • date-fns / Moment.js - Date manipulation
  • Axios - HTTP client (though Fetch API is built-in)
  • RxJS - Reactive programming

State Management

  • Redux / Redux Toolkit
  • Zustand
  • Jotai
  • MobX

Package Installation

Install dependencies via npm/yarn/pnpm as usual:

npm install d3 chart.js axios
npm install -D @types/d3  # TypeScript types

The package.json dependencies are installed during the build process when TelemetryOS builds the application.

External API Integration

REST APIs

Call any REST API accessible from device network:

async function fetchWeather(city) {
  const response = await fetch(
    `https://api.weather.com/v1/current?city=${city}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );
  return response.json();
}

GraphQL

Use GraphQL clients like Apollo or urql:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://graphql.org/swapi-graphql',
  cache: new InMemoryCache()
});

const { data } = await client.query({
  query: gql`
    query GetWeather($city: String!) {
      weather(city: $city) {
        temperature
        conditions
      }
    }
  `,
  variables: { city: 'New York' }
});

WebSocket / Real-Time

Connect to WebSocket servers for real-time updates:

const socket = new WebSocket('wss://echo.websocket.org');

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  updateDisplay(data);
};

socket.send(JSON.stringify({ subscribe: 'weather-updates' }));

Hardware and Platform Features

While applications run in a browser, the TelemetryOS SDK provides JavaScript APIs for hardware and platform features:

  • Camera API - Access device cameras
  • Serial/GPIO - Industrial hardware integration
  • Storage Methods - Multi-scope persistent storage
  • Media Methods - Access TelemetryOS media library
  • Playlist Methods - Control playlist navigation
  • Platform Methods - Device, user, and account information

See SDK Method Reference for complete documentation.

Best Practices

1. Use Modern JavaScript

Target modern Chrome—don't transpile to ES5:

// ✅ Good - Use modern syntax
const data = await fetchData();
const items = array.flatMap(x => x.values);

// ❌ Unnecessary - Don't target old browsers
var data = fetchData().then(function(d) { return d; });

2. Optimize Bundle Size

Devices have limited resources:

  • Tree-shake unused code
  • Use dynamic imports for large dependencies
  • Optimize images and assets
  • Consider bundle size in dependency choices

3. Handle Offline Scenarios

Devices may lose connectivity:

window.addEventListener('online', () => syncData());
window.addEventListener('offline', () => showOfflineUI());

4. Test in Chrome

Since applications run in Chrome, test there:

# Local development
tos serve  # Opens in Chrome

# Production testing
# Deploy to test device running Chrome

5. Use SDK for Platform Features

Don't try to access hardware directly—use the SDK:

// ❌ Won't work - no direct navigator.mediaDevices
const stream = await navigator.mediaDevices.getUserMedia({ video: true });

// ✅ Correct - use SDK camera API
import { camera } from '@telemetryos/sdk';
const photo = await camera().capture();

Development Environment

The local development environment should match production:

Install

npm install -g @telemetryos/cli

Develop

tos init my-app     # Scaffold with Vite + React + TypeScript
cd my-app
tos serve           # Chrome-based development server

Build

npm run build       # Vite/Webpack builds for production

The CLI development server simulates the iframe environment and SDK APIs, providing accurate local testing.

Conclusion

TelemetryOS applications are standard web applications running in Chrome. If it works in a modern Chrome browser and follows iframe security constraints, it will work on TelemetryOS. Use React (recommended) or any JavaScript framework, leverage the full browser API surface, and integrate with external services via standard web APIs. The SDK provides JavaScript APIs for platform-specific features, keeping application code in familiar web development patterns.

Updated 26 days ago

What’s Next