knoopx/vicinae

Vicinae Extensions

Extensions for the Vicinae launcher using TypeScript and React. Two command types: view commands display React UI, no-view commands execute actions without UI.

Creating an Extension

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

Manual setup:

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

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" }
}

View Commands (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>
  );
}

All actions must have an icon prop.

No-View Commands (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 dev server in tmux (creates session only if it doesn't exist)
tmux has -t vicinae-dev || tmux new-session -d -s vicinae-dev 'bunx vici develop'
tmux capture-pane -t vicinae-dev -p -S -   # Read logs

Navigation & Preferences

Navigate between views with useNavigation:

const { push, pop } = useNavigation();
<Action icon={Icon.Eye} title="View" onAction={() => push(<DetailView />)} />;

Define preferences in the manifest and access with getPreferenceValues().

References

See references/ for advanced UX patterns, full API reference, and keyboard shortcuts.