@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

or

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:

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

Content-pinned asset filenames

immutableAssetFileNames() is a separate export (not the workers plugin) that returns a rollupOptions.output partial declaring every emitted /assets/* file as content-pinned via an immutable filename marker:

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

export default defineConfig({
  plugins: [applicationWorkers({ /* ... */ })],
  build: {
    rollupOptions: {
      output: {
        ...immutableAssetFileNames(),
        manualChunks: { /* your own */ },
      },
    },
  },
})

After the build, entries, chunks, and assets are emitted as <name>.immutable.<hash><ext> under /assets/. Legacy-Content-Proxy-Service matches the literal .immutable. marker and serves matched paths with Cache-Control: public, max-age=31536000, immutable. Filenames without the marker stay on the safe revalidate path, so customer builds that don't opt in are unchanged.

Why this is safe under "push over" of the same app version. The content-proxy subdomain is derived from sha1(account + name + version), not from content. Re-pushing the same (account, name, version) reuses the subdomain. Vite's [hash] token is content-derived, so when the source actually changes, the emitted filename changes — old cached files become orphaned, not stale. Re-pushing identical source emits an identical hash and reuses the URL.

Caveat. Don't name source files containing the literal substring immutable between dots (e.g. foo.immutable.ts) — that would propagate into [name] and could read as a marker in an unhashed entry. Vite's [hash] token itself uses base64url characters (A-Za-z0-9_-) with no dots, so the marker only appears where this helper places it.

License

Copyright TelemetryOS