Skip to main content

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.

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 --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 (dark theme)
    └── icon-dark.svg     # Sidebar icon (light 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 with the --dev flag, 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, generate an API key from your account at skyvexsoftware.com and 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:
  1. 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");
  },
});
  1. Update vite.config.ts:
export default createPluginConfig({
  ui: { entry: "src/ui/index.tsx" },
  background: { entry: "src/background/index.ts" },
  vite: {
    plugins: [tailwindcss()],
  },
});
  1. 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