> ## 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.

# Getting Started

> Create your first Stratos plugin in 5 minutes.

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 [developer mode](/sdk/developer-mode) (`--dev` flag) access

***

## 1. Scaffold your plugin

The fastest way to get started:

```bash theme={null}
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 (light theme)
    └── icon-dark.svg     # Sidebar icon (dark theme)
```

Install dependencies:

```bash theme={null}
cd my-plugin
pnpm install
```

***

## 2. Understand the key files

### `plugin.json`

Every plugin needs a manifest. The scaffolder generates this for you:

```json theme={null}
{
  "$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`

```ts theme={null}
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.

<Note>
  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.
</Note>

### `src/ui/index.tsx`

Your plugin's root component. Must be the default export:

```tsx theme={null}
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 in [developer mode](/sdk/developer-mode), log in, and select your airline. Then in your plugin directory:

```bash theme={null}
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:

```bash theme={null}
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, create an API token in your account at [skyvexsoftware.com](https://skyvexsoftware.com) (**Settings → API tokens**) with the **`plugin:upload`** scope ticked, then set it as an environment variable:

```bash theme={null}
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](/sdk/build-and-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`:

```ts theme={null}
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");
  },
});
```

2. Update `vite.config.ts`:

```ts theme={null}
export default createPluginConfig({
  ui: { entry: "src/ui/index.tsx" },
  background: { entry: "src/background/index.ts" },
  vite: {
    plugins: [tailwindcss(), react()],
  },
});
```

3. Add `cross-env` and update build scripts in `package.json`:

```json theme={null}
{
  "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](/sdk/background/overview) 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

* [Architecture](/sdk/architecture) — how the shell loads and runs plugins
* [Plugin Manifest](/sdk/manifest) — full `plugin.json` reference
* [UI Module](/sdk/ui-module) — hooks, styling, and context
* [Background Module](/sdk/background/overview) — running code in the main process
* [Build & Deploy](/sdk/build-and-deploy) — bundling and distribution