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.

These four hooks provide access to shell services from within plugin UI components. They are all thin wrappers around usePluginContext() fields, exported as focused hooks for readability.

​
Import

import {
  useShellNavigation,
  useShellToast,
  useShellConfig,
  usePluginLogger,
} from "@skyvexsoftware/stratos-sdk";

​
useShellNavigation

Access the shell’s navigation helpers. All navigation is handled by the shell’s router — plugins do not manage their own history.

​
Signature

function useShellNavigation(): PluginNavigationHelper

type PluginNavigationHelper = {
  navigateTo(path: string): void;
  navigateToPlugin(pluginId: string, path: string): void;
  navigateToShell(path: string): void;
  getCurrentPath(): string;
};

​
Methods

MethodDescription
navigateTo(path)Navigate to a route within the current plugin (e.g. "history", "settings")
navigateToPlugin(pluginId, path)Navigate to a route in another plugin
navigateToShell(path)Navigate to a shell-level route (e.g. "settings", "debug")
getCurrentPath()Return the current route path string

​
Usage

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

export function Nav() {
  const nav = useShellNavigation();

  return (
    <nav>
      <button onClick={() => nav.navigateTo("history")}>History</button>
      <button onClick={() => nav.navigateToPlugin("pirep-filing", "new")}>
        File PIREP
      </button>
      <button onClick={() => nav.navigateToShell("settings")}>
        App Settings
      </button>
    </nav>
  );
}

​
useShellToast

Trigger toast notifications using the shell’s toast system. All toasts appear in the shell’s notification area — plugins do not render their own toast containers.

​
Signature

function useShellToast(): PluginToastAPI

type PluginToastAPI = {
  success(message: string): void;
  error(message: string): void;
  info(message: string): void;
  warning(message: string): void;
};

​
Usage

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

export function SaveButton() {
  const toast = useShellToast();

  const handleSave = async () => {
    try {
      await saveData();
      toast.success("Settings saved");
    } catch {
      toast.error("Failed to save settings");
    }
  };

  return <button onClick={handleSave}>Save</button>;
}

​
useShellConfig

Read plugin-namespaced config values synchronously. The config store is namespaced to the current plugin — two plugins using the same key will not conflict.

​
Signature

function useShellConfig(): PluginConfigStore

type PluginConfigStore = {
  get<T>(key: string): T | undefined;
  get<T>(key: string, defaultValue: T): T;
};
Note: The UI-side config store provides synchronous reads (values are preloaded into context). This differs from the background PluginContext.config, which has async get, set, delete, and getAll methods.

​
Usage

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

export function MyComponent() {
  const config = useShellConfig();

  // With default value — always returns a string
  const theme = config.get<string>("theme", "dark");

  // Without default — may be undefined
  const apiKey = config.get<string>("apiKey");

  return (
    <div>
      <p>Theme: {theme}</p>
      {!apiKey && <p>API key not configured</p>}
    </div>
  );
}

​
usePluginLogger

Access a scoped logger that routes log output to the shell’s logging infrastructure. Log entries are prefixed with the plugin ID and written to the daily log file alongside all other Stratos logs.

​
Signature

function usePluginLogger(): PluginLogger

type PluginLogger = {
  info(category: string, message: string, ...args: unknown[]): void;
  warn(category: string, message: string, ...args: unknown[]): void;
  error(category: string, message: string, ...args: unknown[]): void;
  debug(category: string, message: string, ...args: unknown[]): void;
};

​
Parameters

Both category and message are required. The category should be the component or service name — it appears in the log entry alongside the plugin ID prefix.
ParameterDescription
categoryComponent or service name (e.g. "FlightMapPage")
messageHuman-readable log message
...argsOptional additional values appended to the log entry

​
Usage

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

export function FlightMapPage() {
  const logger = usePluginLogger();

  useEffect(() => {
    logger.info("FlightMapPage", "Map initialised");
  }, []);

  const handleError = (err: unknown) => {
    logger.error("FlightMapPage", "Failed to load route data", err);
  };

  return <Map onError={handleError} />;
}

​
Never use console.* directly

Plugin components must use usePluginLogger rather than console.log, console.error, etc. The logger writes to the structured log file, applies secret sanitization, and includes the plugin ID prefix for easy filtering. 
// Correct
const logger = usePluginLogger();
logger.info("MyComponent", "User clicked button");

// Wrong — do not use console directly in plugin components
console.log("User clicked button");