What are Workers?

Workers are scripts that run outside of your application's main render and settings views. TelemetryOS supports two types:

• Background Workers run continuously on devices and as Web Workers in the admin portal, even when the application isn't visible in the playlist. They handle data synchronization, scheduled tasks, and background processing.
• Server Workers run as Cloudflare Workers on the edge, providing serverless API endpoints and backend functionality.

Common use cases:

• Fetching data from external APIs
• Synchronizing with inventory or CMS systems
• Monitoring device health
• Caching content for offline use
• Background analytics collection
• Serverless API endpoints

Background Workers

Background workers are defined in the backgroundWorkers field of telemetry.config.json. They start when the playlist containing the application is loaded and continue running in the background.

{
  "name": "my-app",
  "version": "2026.4.0",
  "mountPoints": {
    "render": "/render"
  },
  "backgroundWorkers": {
    "sync": "workers/sync.js"
  }
}

Each key is the worker name, and the value is the path to the built worker file (or an object with a path property).

Example Worker

workers/sync.js:

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

configure();

async function syncData() {
  try {
    // Fetch fresh data from external API
    const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
    const data = await response.json();

    // Store for application to use
    await store().application.set('latest-data', data);

    console.log('Data synced successfully');
  } catch (error) {
    console.error('Sync failed:', error);
  }

  // Schedule next sync
  setTimeout(syncData, 60000); // Every minute
}

// Start sync loop
syncData();

Background Worker Context

• Runs on: Physical devices and as Web Workers in the admin portal
• Lifecycle: Starts when playlist is loaded, continues running in background
• SDK Access: Full SDK API available (storage, media, playlist, etc.)
• No DOM access: Workers are JavaScript contexts without browser DOM

Communication with Render

Workers communicate with the render view through the Storage API:

// Worker writes data
await store().application.set('weather-data', weatherInfo);

// Render subscribes to changes
store().application.subscribe('weather-data', (data) => {
  updateDisplay(data);
});

Server Workers

Server workers run as Cloudflare Workers on the edge, providing serverless API endpoints and backend functionality. They are defined in the serverWorkers field:

{
  "serverWorkers": {
    "api": "workers/api.js",
    "webhook": "workers/webhook.js"
  }
}

Server workers use the Cloudflare Workers runtime (ESM format) and do not have access to the TelemetryOS SDK or browser APIs.

Building Workers

Use the @telemetryos/vite-plugin-application-workers Vite plugin to bundle workers as part of your build:

import { defineConfig } from 'vite'
import { applicationWorkers } from '@telemetryos/vite-plugin-application-workers'

export default defineConfig({
  plugins: [
    applicationWorkers({
      backgroundWorkers: [
        { entry: 'src/workers/sync.ts', outPath: 'workers/sync.js' }
      ],
      serverWorkers: [
        { entry: 'src/workers/api.ts', outPath: 'workers/api.js' }
      ],
    }),
  ],
})

The plugin builds each worker after the main application build completes, using the same Vite configuration (plugins, resolve aliases, environment variables). Background workers are bundled as IIFE format, and server workers are bundled as ESM format with the Cloudflare Vite plugin.

Best Practices

1. Error handling - Workers must be resilient to failures and network issues
2. Periodic execution - Use setTimeout or setInterval for scheduling
3. Resource management - Be mindful of CPU and memory usage on devices
4. Graceful degradation - Applications should work if worker fails
5. Logging - Log important events for debugging in production

Learn More

For complete details on workers, including lifecycle, configuration, and advanced patterns, see the Mount Points documentation.