Background Module

Background modules run in the Electron main process (Node.js). They’re optional — only add one when you need persistent server-side logic that outlives UI navigation: registering Express routes, maintaining a connection, or running scheduled tasks.

When to Use a Background Module

Use a background module when you need to:

Expose an HTTP API to your UI module (via Express routes)
Handle IPC messages from the renderer
Maintain a persistent connection (WebSocket, database, etc.)
Run background polling or scheduled work
Access Node.js APIs not available in the renderer

If your plugin only displays data and reacts to user interaction, a UI module alone is sufficient.

Declaring a Background Module

Add the background entry to your Vite config:

import { createPluginConfig } from "@skyvexsoftware/stratos-sdk/vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default createPluginConfig({
  ui: { entry: "src/ui/index.tsx" },
  background: { entry: "src/background/index.ts" },
  vite: {
    plugins: [tailwindcss(), react()],
  },
});

Adding a background module only adds the background entry — keep react() in the plugins array. createPluginConfig does not inject it for you, and the dev server’s Fast Refresh preamble fails without it. See Getting Started for details. The shell discovers background modules automatically by checking for the compiled background/index.js in your plugin’s install directory — no plugin.json configuration is needed.

The `PluginBackgroundModule` Contract

Your background entry module must export onStart and onStop. Use the createPlugin helper for type safety and validation:

import { createPlugin } from "@skyvexsoftware/stratos-sdk/helpers";

export default createPlugin({
  async onStart(ctx) {
    ctx.logger.info("MyPlugin", "Starting up...");
    // register routes, set up IPC handlers, initialise services
  },

  async onStop(ctx) {
    ctx.logger.info("MyPlugin", "Shutting down...");
    // clean up: close connections, cancel timers, flush data
  },
});

The createPlugin helper validates your module at import time and gives you full type inference on ctx — no manual type imports needed. The shell requires this default export pattern; named exports are not supported.

The Plugin Context

Both onStart() and onStop() receive a ctx object that gives scoped access to shell infrastructure, live flight state, and the pilot. Each accessor is documented on its own page under Plugin Context:

Services — logger, config, ipc, auth, airline, database, server.
Flight & Pilot — flight (state, log, start guards), notify, dialog, prompt.

To talk to your UI module from the background, see Background ↔ UI Communication.

Lifecycle Summary

Shell starts and initialises auth
Shell calls onStart(ctx) for each plugin with a background module
If onStart() throws, the plugin is marked errored — other plugins still load
On shutdown, shell calls onStop(ctx) for each running background module
After an OTA update, the shell calls onStop(ctx) then onStart(ctx) fresh

Getting Started

Plugin Basics

UI Module

Deploy

Type Reference

Background Module

When to Use a Background Module

Declaring a Background Module

The `PluginBackgroundModule` Contract

The Plugin Context

Lifecycle Summary

​When to Use a Background Module

​Declaring a Background Module

​The PluginBackgroundModule Contract

​The Plugin Context

​Lifecycle Summary

When to Use a Background Module

Declaring a Background Module

The `PluginBackgroundModule` Contract

The Plugin Context

Lifecycle Summary