Shell Utility Hooks

These hooks provide access to shell services from within plugin UI components. The first four are thin wrappers around usePluginContext() fields, exported as focused hooks for readability; useTheme follows the theme Stratos is showing.

Import

import {
  useShellNavigation,
  useShellToast,
  useShellConfig,
  usePluginLogger,
  useTheme,
} 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

See PluginNavigationHelper for the full shape.

Methods

Method	Description
`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"`, `"support"`)
`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

See PluginToastAPI for the full shape.

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

See PluginConfigStore for the full shape. 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

See PluginLogger for the full shape.

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.

Parameter	Description
`category`	Component or service name (e.g. `"FlightMapPage"`)
`message`	Human-readable log message
`...args`	Optional 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 sanitisation, 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");

`useTheme`

The theme Stratos is showing, "light" or "dark", with “system” already resolved to whichever the OS is in. Your component renders again whenever it changes. Most of your UI doesn’t need it, because the Tailwind theme tokens switch on their own. Use it for what CSS can’t reach, like an airline logo with light and dark versions. For a map, use StratosMap, which does this for you.

Signature

function useTheme(): "light" | "dark";

Usage

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

export function AirlineLogo({ light, dark }: { light: string; dark: string }) {
  const theme = useTheme();
  return <img src={theme === "dark" ? dark : light} alt="" />;
}

Read the theme with the hook, not once from the page while rendering: that value goes stale when the theme changes and stays wrong until something else renders the component.

Get Started

Developer centre

Plugin Basics

UI Module

Background Module

Deploy

Type Reference

Import

`useShellNavigation`

Signature

Methods

Usage

`useShellToast`

Signature

Usage

`useShellConfig`

Signature

Usage

`usePluginLogger`

Signature

Parameters

Usage

Never use `console.*` directly

`useTheme`

Signature

Usage

​Import

​useShellNavigation

​Signature

​Methods

​Usage

​useShellToast

​Signature

​Usage

​useShellConfig

​Signature

​Usage

​usePluginLogger

​Signature

​Parameters

​Usage

​Never use console.* directly

​useTheme

​Signature

​Usage

Import

`useShellNavigation`

Signature

Methods

Usage

`useShellToast`

Signature

Usage

`useShellConfig`

Signature

Usage

`usePluginLogger`

Signature

Parameters

Usage

Never use `console.*` directly

`useTheme`

Signature

Usage