Vicinae Extensions

Extensions for Vicinae launcher using TypeScript and React.

Contents

• Core Concepts
• Quick Start
• Project Structure
• Command Types
• Development Workflow
• Advanced: UX Patterns
• Advanced: API Reference
• Advanced: Keyboard Shortcuts

Core Concepts

Concept	Description
Extension	Package adding commands to the launcher
View Command	Displays React UI (mode: "view")
No-View Command	Executes action without UI (mode: "no-view")
Manifest	package.json with extension metadata

Quick Start

Recommended: Use Vicinae's built-in "Create Extension" command.

Manual:

mkdir my-extension && cd my-extension
npm init -y
npm install @vicinae/api typescript @types/react @types/node
mkdir src && touch src/command.tsx

Project Structure

my-extension/
├── package.json          # Manifest with commands
├── tsconfig.json
├── src/
│   ├── command.tsx       # View commands
│   └── action.ts         # No-view commands
└── assets/               # Icons

Manifest (package.json)

{
  "name": "my-extension",
  "title": "My Extension",
  "version": "1.0.0",
  "commands": [
    {
      "name": "my-command",
      "title": "My Command",
      "description": "What this command does",
      "mode": "view"
    }
  ],
  "dependencies": {
    "@vicinae/api": "^0.8.2"
  }
}

Command Types

View Command (src/command.tsx)

import { List, ActionPanel, Action, Icon } from "@vicinae/api";

export default function MyCommand() {
  return (
    <List searchBarPlaceholder="Search items...">
      <List.Item
        title="Item"
        icon={Icon.Document}
        actions={
          <ActionPanel>
            <Action
              icon={Icon.Eye}
              title="View"
              onAction={() => console.log("viewed")}
            />
          </ActionPanel>
        }
      />
    </List>
  );
}

Important: All actions must have an icon prop.

No-View Command (src/action.ts)

import { showToast } from "@vicinae/api";

export default async function QuickAction() {
  await showToast({ title: "Done!" });
}

Development Workflow

npm run build         # Production build
npx tsc --noEmit      # Type check

# Run Vicinae dev server in tmux
# Creates the session only if it does not exist
tmux has -t vicinae-dev || tmux new-session -d -s vicinae-dev 'bunx vici develop'

# Read logs
tmux capture-pane -t vicinae-dev -p -S -

Common APIs

import {
  // UI Components
  List,
  Detail,
  Form,
  Grid,
  ActionPanel,
  Action,
  Icon,
  Color,
  // Utilities
  showToast,
  Toast,
  Clipboard,
  open,
  closeMainWindow,
  getPreferenceValues,
  useNavigation,
} from "@vicinae/api";

Keyboard Shortcuts

Common shortcuts: Ctrl+R (refresh), Ctrl+N (new), Ctrl+E (edit), Shift+Delete (delete).

See Keyboard Shortcuts for full reference and implementation examples.

Navigation

function ListView() {
  const { push, pop } = useNavigation();

  return (
    <List.Item
      title="Go to Detail"
      icon={Icon.Document}
      actions={
        <ActionPanel>
          <Action
            icon={Icon.Eye}
            title="View"
            onAction={() => push(<DetailView />)}
          />
        </ActionPanel>
      }
    />
  );
}

Preferences

Define in manifest:

{
  "preferences": [
    {
      "name": "apiKey",
      "title": "API Key",
      "type": "password",
      "required": true
    }
  ]
}

Access in code:

const { apiKey } = getPreferenceValues();

Related Skills

• typescript: Type safety for extensions