Plugin Settings

Settings allow your plugin to be configured by pilots (user-scoped) or by the VA admin platform (airline-scoped). They’re declared in plugin.json and the shell renders a settings UI for pilots automatically: no settings page required in your plugin.

Declaring Settings

Add an available_settings array to your plugin.json:

{
  "available_settings": [
    {
      "key": "welcome_message",
      "name": "Welcome Message",
      "description": "Custom message displayed on the dashboard",
      "type": "longtext",
      "scope": "airline",
      "placeholder": "Enter a welcome message..."
    },
    {
      "key": "show_map",
      "name": "Show Map",
      "description": "Display the flight map on the main page",
      "type": "boolean",
      "scope": "user",
      "default": true
    },
    {
      "key": "units",
      "name": "Unit System",
      "type": "list",
      "scope": "user",
      "default": "imperial",
      "options": [
        { "value": "imperial", "label": "Imperial (ft, kts, lbs)" },
        { "value": "metric", "label": "Metric (m, km/h, kg)" }
      ]
    },
    {
      "key": "refresh_interval",
      "name": "Refresh Interval",
      "description": "How often to refresh data (seconds)",
      "type": "range",
      "scope": "user",
      "default": 30,
      "min": 5,
      "max": 120,
      "step": 5
    }
  ]
}

Setting Types

Type	Rendered As	Extra Fields
`boolean`	Toggle switch	`default?: boolean`
`text`	Text input	`default?`, `pattern?`, `placeholder?`
`longtext`	Textarea	`default?`, `placeholder?`
`number`	Number input	`default?`, `min?`, `max?`, `step?`
`range`	Slider	`default?`, `min` (required), `max` (required), `step?`
`list`	Dropdown select	`default?`, `options` (required)
`radio`	Radio group	`default?`, `options` (required)
`date`	Date picker	`default?`
`json`	Monospace textarea	`default?`

For list and radio types, options is an array of { value: string; label: string } objects.

Setting Scopes

`"user"` scope

Appears on your plugin’s page in Stratos Settings → Plugins. Each pilot can configure their own value independently. Use user-scoped settings for:

Unit system preferences (imperial vs metric)
Display toggles (show/hide sections)
Notification preferences
Refresh intervals

`"airline"` scope

Set by the airline on skyvexsoftware.com and pushed to all pilots. Not shown to pilots in Stratos. Stratos fetches the values when the pilot signs in and picks up the airline’s changes while it’s running, holding them until the flight ends if one is in progress (see Reacting to airline changes). Use airline-scoped settings for:

Welcome messages and branding
Quick links and resources
Event detection rules
Route configurations
Any content the VA wants to control centrally

Airline-scoped settings can be updated on skyvexsoftware.com without rebuilding or redeploying the plugin. The airline sets them on your plugin’s Settings tab in Console. Each setting gets one row, drawn to match its type:

Fuel Policy's Settings tab in Console, built from the airline-scoped settings in its plugin.json

Reading Settings in the UI

Use usePluginContext() to access settings from any component:

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

function MyComponent() {
  const ctx = usePluginContext();

  const welcomeMsg = ctx.config.get<string>("welcome_message", "Hello!");
  const links = ctx.config.get<QuickLink[]>("quick_links", []);

  return (
    <div className="p-6">
      <p className="text-lg">{welcomeMsg}</p>
    </div>
  );
}

Or with the useShellConfig() hook directly:

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

function MyComponent() {
  const config = useShellConfig();
  const welcomeMsg = config.get<string>("welcome_message", "Hello!");
}

UI config access is synchronous: values are available immediately on render.

Note: config.get() in the UI context reads airline-scoped settings only: those managed by the airline on skyvexsoftware.com. User-scoped settings (personal preferences like unit system, display toggles, and refresh intervals) are managed through the shell’s settings UI and are not accessible via this API.

Reading Settings in a Background Module

Background config access uses ctx.config and is async:

import type { PluginContext } from "@skyvexsoftware/stratos-sdk";

export async function onStart(ctx: PluginContext): Promise<void> {
  const interval = await ctx.config.get<number>("refresh_interval", 30);
  const links = await ctx.config.get<object[]>("quick_links", []);

  ctx.logger.info("Init", `Starting with interval=${interval}s`);
}

Always Provide Defaults

Your plugin should work out of the box without any settings configured. The second argument to config.get is the fallback value returned when the setting has not been set:

// Falls back to 30 if never configured
const interval = ctx.config.get<number>("refresh_interval", 30);

// Falls back to true if never configured
const showMap = ctx.config.get<boolean>("show_map", true);

// Falls back to empty array
const links = ctx.config.get<QuickLink[]>("quick_links", []);

Never assume a setting has a value: always pass a sensible default.

Get Started

Developer centre

Plugin Basics

UI Module

Background Module

Deploy

Type Reference

Declaring Settings

Setting Types

Setting Scopes

`"user"` scope

`"airline"` scope

Reading Settings in the UI

Reading Settings in a Background Module

Always Provide Defaults

​Declaring Settings

​Setting Types

​Setting Scopes

​"user" scope

​"airline" scope

​Reading Settings in the UI

​Reading Settings in a Background Module

​Always Provide Defaults

Declaring Settings

Setting Types

Setting Scopes

`"user"` scope

`"airline"` scope

Reading Settings in the UI

Reading Settings in a Background Module

Always Provide Defaults