> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Background Module

> Running code in the Electron main process.

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:

```ts theme={null}
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](/sdk/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:

```ts theme={null}
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](/sdk/background/context/overview):

* **Services** — [`logger`](/sdk/background/context/logger), [`config`](/sdk/background/context/config), [`ipc`](/sdk/background/context/ipc), [`auth`](/sdk/background/context/auth), [`airline`](/sdk/background/context/airline), [`database`](/sdk/background/context/database), [`server`](/sdk/background/context/server).
* **Flight & Pilot** — [`flight`](/sdk/background/context/flight) (state, log, start guards), [`notify`](/sdk/background/context/notify), [`dialog`](/sdk/background/context/dialog), [`prompt`](/sdk/background/context/prompt).

To talk to your UI module from the background, see [Background ↔ UI Communication](/sdk/background/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