Vicinae Extensions

Build 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

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>
      <List.Item
        title="Item"
        icon={Icon.Document}
        actions={
          <ActionPanel>
            <Action title="Select" onAction={() => console.log("selected")} />
          </ActionPanel>
        }
      />
    </List>
  );
}

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

# Dev mode with watch (use tmux for background)
tmux new -d -s vicinae-dev 'npm run dev'

Common APIs

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

Navigation

function ListView() {
  const { push, pop } = useNavigation();
  
  return (
    <List.Item
      title="Go to Detail"
      actions={
        <ActionPanel>
          <Action 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();

Raycast Compatibility

Vicinae runs most Raycast extensions. To test:

cd raycast-extension
npm install --save-dev @vicinae/api
npx vici develop

Related Skills

• typescript: Type safety for extensions