Plugins are built with Vite using a shared config factory from the SDK. The output is zipped and uploaded to the Skyvex website for distribution.
Vite Configuration
Use createPluginConfig() from the SDK:
// 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" },
background: { entry: "src/background/index.ts" }, // optional
vite: {
plugins: [tailwindcss(), react()],
},
});
The vite option accepts any Vite config to merge in — plugins, resolve aliases, CSS config, etc.
@vitejs/plugin-react is required, not optional. The SDK injects a React Fast Refresh preamble into your entry file that imports from /@react-refresh — an endpoint only served when react() is registered. Without it, pnpm dev against a running Stratos will fail to load the plugin UI with a cross-origin module error.
If you only have a UI module, omit the background field.
Build Scripts
With background module:
{
"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",
"bundle": "pnpm build && stratos-deploy"
}
}
UI-only plugin:
{
"scripts": {
"dev": "vite",
"build": "vite build",
"bundle": "pnpm build && stratos-deploy"
}
}
Use cross-env for Windows compatibility with the BUILD_TARGET environment variable.
How the Build Works
UI build (default): Compiles your React code into a single ESM bundle. Shared dependencies are externalised and resolved from the shell at runtime via window.__stratos_modules__.
Background build (BUILD_TARGET=background): Compiles your Node.js module into an ESM bundle. Electron, Node.js builtins, and the SDK are externalised.
CSS and Static Assets
Plugins are loaded at runtime via import(), so CSS and assets must be embedded in the JS bundle — separate files won’t be loaded.
CSS injection is handled automatically. Any CSS you import (including Tailwind output from @tailwindcss/vite) is injected into the DOM as a <style> tag when your plugin module loads. The shell wraps all plugin CSS in @layer plugin to prevent your styles from overriding the shell’s UI — you don’t need to do anything special for this.
Your plugin’s styles.css should include Tailwind and a @source directive so Tailwind can find your component files:
@import "tailwindcss";
@source "./**/*.{ts,tsx}";
Import it in your plugin’s entry file:
import "./styles.css";
import "./hero-banner.css"; // any additional custom CSS
Static assets (images, SVGs, fonts) under 10 MB are inlined as data URIs automatically. Import them as usual and use the result as a src:
import logo from "./assets/logo.svg";
import badge from "../assets/badge-icon.svg";
<img src={logo} alt="Logo" />
<img src={badge} alt="Badge" className="h-5 w-5" />
This works for any file type Vite can handle (.svg, .png, .jpg, .webp, .woff2, etc.).
What Gets Externalized
You do not need to bundle these — the shell provides them at runtime:
UI externals:
react, react-dom
@tanstack/react-query, @tanstack/react-router
@skyvexsoftware/stratos-sdk
sonner, socket.io-client
maplibre-gl, react-map-gl/maplibre
Background externals:
electron
@skyvexsoftware/stratos-sdk (except /helpers, which is bundled into your plugin)
socket.io-client
- All Node.js built-in modules
Anything else you import (e.g. lucide-react, your own utilities) will be bundled into your plugin.
Build Output
After pnpm build, the dist/ directory contains:
dist/
├── plugin.json ← copied from root
├── assets/ ← icons (for sidebar display)
│ ├── icon-light.svg
│ └── icon-dark.svg
├── ui/
│ └── index.js ← bundled UI module (ESM, CSS + assets inlined)
└── background/ ← only if background module exists
└── index.js ← bundled background module (ESM)
CSS and imported static assets are embedded directly in ui/index.js — there are no separate .css files in the output.
Development Workflow
Live Reload Development
The recommended development workflow uses the Stratos app’s developer mode:
- Open Stratos with the
--dev flag
- Log in and select your airline
- In your plugin directory:
Your plugin’s Vite dev server auto-connects to Stratos via Socket.io. The plugin appears in the sidebar immediately. Code changes auto-reload in about a second.
✓ Vite dev server running at http://localhost:5174
✓ Connected to Stratos (localhost:2066)
✓ Plugin "my-plugin" mounted
| Change | Behavior |
|---|
UI component code (src/ui/**) | Auto-reloads on save |
| CSS / Tailwind classes | Auto-reloads on save |
Background module (src/background/**) | Auto-rebuilds and hot-reloads |
plugin.json | Restart pnpm dev |
| New dependencies | Run pnpm install then restart pnpm dev |
Manual Testing (No Dev Server)
If you prefer to test with a production build:
- Run
pnpm build
- Copy the
dist/ contents to Stratos’s plugins directory:
| Platform | Path |
|---|
| macOS | ~/Library/Application Support/Stratos/plugins/my-plugin/ |
| Windows | %APPDATA%\Stratos\plugins\my-plugin\ |
| Linux | ~/.config/Stratos/plugins/my-plugin/ |
- Restart Stratos — it discovers plugins by finding
plugin.json in each subdirectory.
Tip: Symlink your dist/ directory to skip the copy step:
# macOS
ln -s "$(pwd)/dist" ~/Library/Application\ Support/Stratos/plugins/my-plugin
Deploying
Quick Deploy
The SDK includes a stratos-deploy CLI that bundles and uploads your plugin in one step:
This runs pnpm build, zips dist/ into bundle.zip, and uploads it to the Skyvex API. Your package.json should have:
{
"scripts": {
"bundle": "pnpm build && stratos-deploy"
}
}
If you scaffolded your plugin with create-stratos-plugin, this script is already included.
Authentication
Create an API token in your account settings at skyvexsoftware.com — under Settings → API tokens — and tick the plugin:upload scope. Then set it as an environment variable:
SKYVEX_API_TOKEN=your-token pnpm bundle
The token must carry the plugin:upload scope. Uploads made with a token that lacks it are rejected with 403 Invalid scope(s) provided. Scopes are fixed when a token is created, so if your token predates this requirement, create a new one with plugin:upload ticked and revoke the old one.
The plugin ID and version are read from plugin.json automatically. On success, the Skyvex server validates, signs, and publishes your plugin to the CDN.
Manual Upload
If you don’t have an API token or prefer to upload through the website:
Without SKYVEX_API_TOKEN, the command still builds and creates bundle.zip — it just skips the upload and tells you where to upload manually at skyvexsoftware.com.
CI/CD
For automated deployments, set SKYVEX_API_TOKEN as a secret in your CI environment:
# GitHub Actions example
- name: Deploy plugin
run: pnpm bundle
env:
SKYVEX_API_TOKEN: ${{ secrets.SKYVEX_API_TOKEN }}
Full GitHub Actions Workflow
Drop this in your plugin repo at .github/workflows/deploy.yml for a complete deploy pipeline that builds the bundle and uploads it to Skyvex on every push to main:
.github/workflows/deploy.yml
name: Deploy plugin to Skyvex
# ──────────────────────────────────────────────────────────────
# Builds the plugin and uploads a new version to the Skyvex
# platform. The Skyvex API handles signing, CDN upload, and
# metadata generation from the bundle.
#
# Required GitHub Actions secret:
# SKYVEX_API_TOKEN – Passport bearer for the Skyvex API
# ──────────────────────────────────────────────────────────────
on:
workflow_dispatch:
push:
branches: [main]
paths:
- "src/**"
- "assets/**"
- "plugin.json"
- "package.json"
- "pnpm-lock.yaml"
- "vite.config.ts"
- "tsconfig.json"
- ".github/workflows/deploy.yml"
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 10
- name: Read manifest
id: manifest
run: |
VERSION=$(jq -r '.version' plugin.json)
PLUGIN_ID=$(jq -r '.id' plugin.json)
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
echo "plugin_id=$PLUGIN_ID" >> "$GITHUB_OUTPUT"
echo "Plugin: $PLUGIN_ID v$VERSION"
- name: Install dependencies
run: pnpm install --frozen-lockfile
timeout-minutes: 5
- name: Build plugin
run: pnpm build
- name: Create bundle.zip
run: |
cd dist
zip -r ../bundle.zip .
cd ..
echo "Bundle size: $(du -h bundle.zip | cut -f1)"
- name: Upload to Skyvex API
env:
SKYVEX_API_TOKEN: ${{ secrets.SKYVEX_API_TOKEN }}
SKYVEX_API_URL: https://skyvexsoftware.com/api/stratos
run: |
PLUGIN_ID="${{ steps.manifest.outputs.plugin_id }}"
RESPONSE=$(curl -s -w "\n%{http_code}" \
-X POST "${SKYVEX_API_URL}/plugins/${PLUGIN_ID}/versions" \
-H "Authorization: Bearer ${SKYVEX_API_TOKEN}" \
-H "Accept: application/json" \
-F "file=@bundle.zip")
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')
if [ "$HTTP_CODE" -ne 201 ]; then
echo "Upload failed (HTTP $HTTP_CODE):"
echo "$BODY"
exit 1
fi
echo "Plugin uploaded and signing initiated:"
echo "$BODY" | jq .
Setup steps:
- Add the workflow file at
.github/workflows/deploy.yml in your plugin repo.
- Generate an API token at skyvexsoftware.com under Settings → API tokens, with the
plugin:upload scope ticked.
- Add the secret in your GitHub repo: Settings → Secrets and variables → Actions → New repository secret. Name it
SKYVEX_API_TOKEN and paste the token.
- Bump
plugin.json version before each push — the API rejects duplicate versions.
- Push to
main (or trigger manually from the Actions tab). The workflow builds the bundle and uploads it; the Skyvex API handles signing and CDN publishing.
The workflow only runs when files that affect the bundle change — edits to README.md or unrelated files won’t trigger a deploy. Use workflow_dispatch to force a run from the Actions tab.
What Happens After Upload
- The Skyvex API validates your
plugin.json manifest
- An
.integrity file is generated with SHA256 hashes for every file in your bundle
- The bundle is signed with Ed25519 and republished to the CDN
latest.json is updated so Stratos clients detect the new version
- Users receive the update automatically
Troubleshooting
| Error | Cause | Fix |
|---|
| ”No built plugin found” | dist/ doesn’t exist | Run pnpm build first, or use pnpm bundle which builds automatically |
| ”Version X already exists” | This version is already published | Bump the version in plugin.json |
| ”Authentication failed” | Invalid or expired token | Generate a new token at skyvexsoftware.com |
| ”Invalid scope(s) provided” | Token is missing the plugin:upload scope | Create a new token with plugin:upload ticked — scopes can’t be added to an existing token |
| ”Permission denied” | Token doesn’t own this plugin | Check you’re using the correct account’s token |
| ”Build output incomplete” | dist/ui/index.js is missing | Check your Vite config and build output |
Airline Plugin Sync
When a plugin has "type": "airline", the VA platform manages distribution. Stratos automatically syncs the plugin set on authentication:
- Pilot logs in to their VA
- Shell fetches the airline’s public plugin list (every plugin the VA has installed for everyone, plus core plugins)
- After relay-token authentication, the shell fetches the pilot-scoped list — this returns the airline-wide plugins plus any extras the VA admin has assigned to that specific pilot
- Missing plugins are downloaded and installed automatically; removed plugins are cleaned up
- Updates are applied automatically when new versions are published
VA admins choose, per plugin, whether to install it for all pilots or only for selected pilots from the airline management panel. Pilot-specific assignments only appear in the post-login (relay-authenticated) plugin list, never in the public airline list.
For "user" type plugins, pilots install them manually.