Getting Started

This guide walks you through creating a Stratos plugin from scratch — a React component that appears in the Stratos sidebar with live reload during development.

Prerequisites

Node.js 20+
pnpm (recommended)
The Stratos app installed with developer mode (--dev flag) access

1. Scaffold your plugin

The fastest way to get started:

pnpx create-stratos-plugin

This prompts you for a plugin name, author, and type, then generates a ready-to-develop project with Tailwind CSS, TypeScript, and Vite preconfigured. Your project structure:

my-plugin/
├── .gitignore
├── plugin.json           # Plugin manifest
├── package.json
├── vite.config.ts        # Build config (uses SDK)
├── tsconfig.json
├── src/
│   └── ui/
│       ├── index.tsx     # UI entry point
│       └── styles.css    # Tailwind CSS + source config
└── assets/
    ├── icon-light.svg    # Sidebar icon (light theme)
    └── icon-dark.svg     # Sidebar icon (dark theme)

Install dependencies:

cd my-plugin
pnpm install

2. Understand the key files

`plugin.json`

Every plugin needs a manifest. The scaffolder generates this for you:

{
  "$schema": "https://cdn.skyvexsoftware.com/schemas/stratos-plugin.json",
  "id": "my-plugin",
  "type": "airline",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "A custom plugin for our VA",
  "author": {
    "id": "my-va",
    "name": "My Virtual Airline"
  },
  "icon_light": "icon-light.svg",
  "icon_dark": "icon-dark.svg"
}

The id must be unique — lowercase alphanumeric and hyphens only. The type controls distribution: "airline" plugins are synced to all pilots by the VA; "user" plugins are installed individually.

`vite.config.ts`

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" },
  vite: {
    plugins: [tailwindcss(), react()],
  },
});

createPluginConfig handles everything: externalising shared dependencies (React, TanStack Query, the SDK), ESM output format, asset copying, and dev server auto-connect. The vite option lets you add extra Vite config like Tailwind and React.

Keep react() in the plugins array — it’s required for the dev server, not just a convenience. The SDK injects a Fast Refresh preamble that imports /@react-refresh, which is only served when @vitejs/plugin-react is registered.

`src/ui/index.tsx`

Your plugin’s root component. Must be the default export:

import { usePluginContext } from "@skyvexsoftware/stratos-sdk";
import "./styles.css";

export default function Plugin() {
  const { pluginId } = usePluginContext();

  return (
    <div className="p-6">
      <h1 className="text-xl font-semibold text-foreground">{pluginId}</h1>
      <p className="mt-2 text-sm text-text-muted">Hello from your Stratos plugin!</p>
    </div>
  );
}

The shell mounts this component at /plugins/my-plugin and wraps it with providers that supply plugin context, error boundaries, and theme.

3. Develop with live reload

Start the Stratos app in developer mode, log in, and select your airline. Then in your plugin directory:

pnpm dev

You’ll see:

✓ Vite dev server running at http://localhost:5174
✓ Connected to Stratos (localhost:2066)
✓ Plugin "my-plugin" mounted

Your plugin appears in the Stratos sidebar immediately. Edit your code — changes auto-reload in about a second.

4. Bundle and deploy

When you’re ready to ship:

pnpm bundle

This builds your plugin, zips dist/ into bundle.zip, and uploads it to Skyvex automatically if you have an API token set. The scaffolder already added this script to your package.json. To enable automatic uploads, create an API token in your account at skyvexsoftware.com (Settings → API tokens) with the plugin:upload scope ticked, then set it as an environment variable:

SKYVEX_API_TOKEN=your-token pnpm bundle

Without the token, the command still creates bundle.zip for manual upload through the website. See Build & Deploy for CI/CD setup, release modes, and troubleshooting.

Adding a background module

If your plugin needs server-side functionality (Express routes, IPC handlers, database access), add a background module:

Create src/background/index.ts:

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

export default createPlugin({
  async onStart(ctx) {
    ctx.logger.info("MyPlugin", "Background started");
  },
  async onStop(ctx) {
    ctx.logger.info("MyPlugin", "Background stopped");
  },
});

Update vite.config.ts:

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

Add cross-env and update build scripts in package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build && cross-env BUILD_TARGET=background vite build",
    "build:ui": "vite build",
    "build:bg": "cross-env BUILD_TARGET=background vite build"
  }
}

See Background Module for the full API reference.

Tips

Use useSimData with a select option to pull only the fields you need — avoids unnecessary re-renders on every simulator tick
Background modules are optional — most plugins only need a UI
Your plugin gets the same Tailwind setup as Stratos, so utility classes just work
The SDK is a dev dependency — Stratos provides React, TanStack Query, and Socket.io at runtime so your bundle stays small
Check the logs at Settings > Logs if something isn’t connecting

Next steps

Architecture — how the shell loads and runs plugins
Plugin Manifest — full plugin.json reference
UI Module — hooks, styling, and context
Background Module — running code in the main process
Build & Deploy — bundling and distribution

Plugin Basics

UI Module

Background Module

Deploy

Type Reference

Getting Started

Prerequisites

1. Scaffold your plugin

2. Understand the key files

`plugin.json`

`vite.config.ts`

`src/ui/index.tsx`

3. Develop with live reload

4. Bundle and deploy

Adding a background module

Tips

Next steps

​Prerequisites

​1. Scaffold your plugin

​2. Understand the key files

​plugin.json

​vite.config.ts

​src/ui/index.tsx

​3. Develop with live reload

​4. Bundle and deploy

​Adding a background module

​Tips

​Next steps

Prerequisites

1. Scaffold your plugin

2. Understand the key files

`plugin.json`

`vite.config.ts`

`src/ui/index.tsx`

3. Develop with live reload

4. Bundle and deploy

Adding a background module

Tips

Next steps