@stnd/launcher
Circle 2 — Application Superpower (Official Extension) · Stable · First-Party
Role: Global
Cmd+Kcommand palette, fuzzy action search, keyboard shortcut dispatcher, and custom modal views.When to use: Register module commands via the
launcher:actionhook inindex.module.jsso users can trigger actions from anywhere.
Quick Start (TL;DR)
// modules/my-feature/index.module.js
export default {
id: "my-feature",
hooks: { "launcher:action": ["./actions/commands.js"] },
};
The Universal Command Palette engine for the Standard Framework.
@stnd/launcher provides a centralized interface for command execution, navigation, and view management. It adheres to the “Standard” design philosophy: clean, keyboard-centric, and extensible.
ELI5
Cmd+K on any Standard site — that’s this. A registry holds every command and “view” (a full Svelte panel, like Settings or the file navigator) any loaded module has registered; the palette searches across all of it. A module adds its own command by calling register() once; it shows up in the palette for everyone, no wiring needed on the app’s side.
It’s already on — @stnd/launcher is a Gold Standard module. To add your own command from inside a module:
import { register } from "@stnd/launcher";
register("::my-command", { title: "Do the thing", icon: "star" }, () => doTheThing());
Architecture
The Launcher follows a Reactive Core pattern:
- Engine (
launcher.ts): Manages state (registry, palette, views), search logic, and public API. - UI (
Launcher.svelte): A “dumb” view component that subscribes to the engine state and renders the appropriate interface. - Modules: Extend the launcher by registering commands and views via
virtual:stnd/components.
Usage
Import and mount the <Launcher /> component in your layout:
<script>
import Launcher from "@stnd/launcher/Launcher.svelte";
</script>
<!--
load: Optional allow-list of commands/views to enable.
If omitted, all registered commands are loaded.
-->
<Launcher />
Props
| Prop | Type | Default | Description |
|---|---|---|---|
load |
string | string[] | function |
null |
Accepted for backward compatibility; it has no effect. |
userStore |
readable |
null |
Svelte store containing the current user. |
searchNotes |
function |
null |
Async function to search app content. |
WelcomeView |
Component |
null |
Custom component for the empty state. |
FooterView |
Component |
null |
Custom component for the optional launcher footer. |
footer |
Snippet |
null |
Svelte 5 snippet for custom footer content. |
showFooter |
boolean | "always" |
false |
Enable built-in footer (navigation hints & info). |
Core Concepts
Registry
The registry holds all available Commands and Views.
- Commands: Executable actions (functions).
- Views: Interactive components rendered within the launcher window.
Sizing
The launcher window adapts to its content.
- Standard: Default command palette size.
- Wide: Extended width for rich content.
- Tall: Extended height for browsing.
Views can request size changes dynamically:
// In your view component
let { setSize } = $props();
// Expand window
setSize({ width: "wide", height: "tall" });
API (launcher.ts)
import {
initLauncher,
register,
launcherView,
launcherToggle,
setSize,
} from "@stnd/launcher";
initLauncher(options)
Initialize the engine with app-specific logic.
register(trigger, meta, handler)
Register a new command or view.
- trigger: Unique ID (e.g.,
::my-view). - meta: Configuration object for the command/view.
title(string): Display name.desc(string): Short description.icon(string): Icon identifier.size(object): Window dimensions{ width, height }.requireAuth(boolean): Iftrue, only shown to authenticated users.requireGuest(boolean): Iftrue, only shown to unauthenticated users.requireRole(string | string[]): Restricts visibility to users with specific roles (e.g.,"admin").context(string | string[]): Restricts visibility to specific application states (e.g.,"editor").
- handler: Function (action) or Svelte Component (view).
launcherView(view, props)
Switch the active view.
- view: Trigger ID of the view.
- props: Data to pass to the view component.
Keyboard: Esc
The launcher registers Esc with the keyboard module:
- Default behavior: Steps back in browser history when the launcher is closed.
- Custom override (
stnd:escape): Before stepping back, the launcher dispatches a cancelablestnd:escapeevent onwindow. Any app that wantsEscto navigate elsewhere (e.g. returning to an overview panel instead of browser history) can listen forstnd:escapeand callevent.preventDefault(). - Production example: The àVélo app intercepts
stnd:escapeinapps/avelo-stat/modules/core/scripts/shortcuts.tsto return to its station overview.
Data Attributes
The UI listens for clicks on elements with specific data attributes:
data-launcher-toggle: Toggles the launcher.data-launcher-view="::id": Opens a specific view.data-launcher-prompt="text": Opens launcher with pre-filled text.