What Are Vicinae Extensions and How Do You Build or Run Them?

Updated

Vicinae extensions are add-ons that give the Vicinae desktop launcher new commands and custom interfaces. You build them with React and TypeScript, and Vicinae renders your code as native UI rather than in a browser. You can also run many existing Raycast extensions and script commands without rewriting them. This applies if you use Vicinae on Linux, macOS, or Windows and want to go beyond the built-in features.

What extensions add to the launcher

Vicinae ships with a set of built-in tools: application launching, file search, clipboard history, a calculator, an emoji picker, window management, browser tabs, fonts, theming, power management, shortcuts, and scripts. Extensions are how you add anything beyond that list.

The launcher is designed around a single keyboard-driven interface: one shortcut opens everything, and you navigate, filter, and act without touching the mouse. An extension plugs into that same flow, so a custom command behaves like a built-in one instead of opening a separate app window.

How building an extension works

The model is close to building a normal React app:

  1. Write the extension in React and TypeScript using the API described in Vicinae's documentation.
  2. Render through Vicinae — your components become native UI, with no embedded browser involved.
  3. Run it from the launcher like any built-in command.

The practical benefit is that you reuse familiar React patterns (components, state, props) while the launcher handles presentation and keyboard interaction. The documentation is the place to confirm the exact API surface before you start; the site links to it directly rather than spelling out every hook.

Running Raycast extensions and scripts

Vicinae states that it can run many Raycast extensions and script commands out of the box, which matters if you already have a macOS workflow built around Raycast and want to bring it to Linux.

Two cautions follow from the wording:

  • "Many" is not "all." Compatibility is not claimed as complete, so test the specific extension you depend on rather than assuming it will work.
  • Script commands are a separate path from React/TypeScript extensions. If an extension relies on Raycast-specific behavior, the script route may be the simpler fallback.

Finding documentation and existing extensions

The site provides two direct entry points under its "Build your own" section: Documentation and Browse Extensions. Start with Browse Extensions if you want to see what already exists or find a reference implementation; start with Documentation if you are writing your own.

Vicinae is free and open source, with community channels on Discord and GitHub, plus sponsorship options. Those are the right places to ask about API details or report an extension that does not behave as expected.

Platform availability

Vicinae lists Linux, macOS, and Windows as supported platforms, and the install command shown on the site is a shell one-liner (curl -fsSL https://vicinae.com/install | bash), with other installation methods also offered. The extension-building story is presented as platform-neutral — React and TypeScript code rendered as native UI — but the site does not break down extension support per operating system. If you are on macOS or Windows rather than Linux, verify your target extension on your own machine before relying on it.

Deciding whether to build or reuse

Your situation Sensible starting point
You want a small custom command Write a TypeScript/React extension
You already use a Raycast extension Try running it directly, then fall back to a script command if it misbehaves
You just want more from the launcher Browse existing extensions first
You need exact API behavior Read the documentation before writing code

The main constraint to keep in mind is that compatibility with Raycast is described as partial, so "it works in Raycast" is a reason to try, not a guarantee.