@telemetryos/vite-plugin-application-workers

A Vite plugin for bundling TelemetryOS application workers alongside your application.

Overview

This plugin helps you bundle workers for TelemetryOS applications. Workers are features of TelemetryOS that allow applications to run code in dedicated contexts:

Background Workers: Run continuously in the background on the player (device) and in the user admin as Web Workers, even when the application's iframe is not loaded
Server Workers: Run as Cloudflare Workers on the edge, providing serverless API endpoints and backend functionality

This plugin makes it easy to bundle these workers as part of your Vite build process.

Installation

npm install @telemetryos/vite-plugin-application-workers --save-dev

pnpm add @telemetryos/vite-plugin-application-workers -D

Usage

Add the plugin to your vite.config.ts:

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

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

Configuration

The plugin accepts an options object with the following properties:

`backgroundWorkers`

Type: WorkerConfig[] Default: []

An array of background worker configurations. Background workers run as Web Workers on the player and in the user admin.

Each worker configuration has:

entry (string, required): The path to the source entry file for the worker
- Example: 'src/workers/background.ts'
outPath (string, required): The output path relative to the dist folder where the worker will be written
- Example: 'workers/background.js'

`serverWorkers`

Type: WorkerConfig[] Default: []

An array of server worker configurations. Server workers run as Cloudflare Workers on the edge.

Each worker configuration has the same properties as background workers:

entry (string, required): The path to the source entry file for the Cloudflare Worker
- Example: 'src/workers/api.ts'
outPath (string, required): The output path relative to the dist folder where the worker will be written
- Example: 'workers/api.js'

Example with Multiple Workers

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',
        },
        {
          entry: 'src/workers/notifications.ts',
          outPath: 'workers/notifications.js',
        },
      ],
      serverWorkers: [
        {
          entry: 'src/workers/api.ts',
          outPath: 'workers/api.js',
        },
        {
          entry: 'src/workers/webhook.ts',
          outPath: 'workers/webhook.js',
        },
      ],
    }),
  ],
})

Registering Workers with TelemetryOS

After building your workers, you need to register them in your telemetry.config.json file so TelemetryOS knows about them:

{
  "name": "My Application",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  },
  "backgroundWorkers": {
    "background": "workers/background.js",
    "sync": "workers/sync.js"
  },
  "serverWorkers": {
    "api": "workers/api.js",
    "webhook": "workers/webhook.js"
  },
  "devServer": {
    "runCommand": "vite",
    "url": "http://localhost:5173"
  }
}

Both backgroundWorkers and serverWorkers objects map worker names to their paths:

The key (e.g., "background" or "api") is the worker name used to reference the worker
The value is the path to the built worker file relative to your dist folder

How It Works

The plugin:

Runs after your main application build completes
Builds each configured worker using the same Vite configuration as your main application (plugins, resolve aliases, environment variables, etc.)
Outputs each worker to the specified location in your dist folder
Background workers are bundled as IIFE (Immediately Invoked Function Expression) format for Web Workers
Server workers are bundled as ESM (ES Module) format with the Cloudflare Vite plugin for Cloudflare Workers runtime

JSPM