Skip to main content
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 tailwindcss from "@tailwindcss/vite";

export default createPluginConfig({
  ui: { entry: "src/ui/index.tsx" },
  background: { entry: "src/background/index.ts" },
  vite: {
    plugins: [tailwindcss()],
  },
});
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: To talk to your UI module from the background, see Background ↔ UI Communication.

​
Lifecycle Summary

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