1. Project Overview & Quickstart (vicinaehq/vicinae) Copy Chapter

File: README.md Copy Chapter

**Vicinae**

A focused launcher for your desktop

Vicinae (pronounced "vee-CHEE-nay") is a high-performance, native command palette for your desktop.

Out of the box, Vicinae can be your:

• app search
• clipboard history
• text expander (snippets)
• file search
• browser tab switcher
• emoji picker
• calculator
• window switcher
• font browser
• volume controller

When you need more, Vicinae can be extended in several ways:

• React/Typescript extensions, compatible with the Raycast ecosystem. In-app integration with the Vicinae store and the Raycast store.
• Script commands, also compatible with the Raycast feature of the same name, with special Vicinae additions.
• dmenu style menu creation, the linux minimalist way!

Documentation Copy Chapter

Everything you need to know to get started with Vicinae is at vicinae.com. If you have any question, please feel free to come ask it on discord!

Sponsors Copy Chapter

Gold sponsors Copy Section

Silver Sponsors Copy Section

Supporter sponsors Copy Section

And all our other amazing sponsors!

Acknowledgments Copy Chapter

Special thanks to the Soulver team for allowing us to ship SoulverCore as the default calculator backend on macOS.

File: extra/extension-boilerplate/assets/README.md Copy Chapter

Vicinae Extension

Congratulations on generating your new Vicinae extension!

You can install the required dependencies and run your extension in development mode like so:

npm install
npm run dev

If you want to build the production bundle, simply run:

npm run build

File: extra/extension-boilerplate/README.md Copy Chapter

Template extension

This extension is a collection of command templates to build extensions from.

The content of this repository is also used to generate the build time assets required to provide the "Create Extension" command
from within Vicinae (vicinae://extensions/vicinae/developer/create)

To make developing templates easy, this repo itself is a valid Vicinae extension and you can run it in development mode like any other:

npm install
npm run dev

File: scripts/runners/appimage/README.md Copy Chapter

Building the AppImage

Issuing the following command will start building the app image and output it at the root of vicinae source tree:

docker run -v/path/to/vicinae/source:/work --cap-add SYS_ADMIN --device /dev/fuse appimage-builder -c 'make clean && make appimage'

From there you should be able to execute the appimage on a variety of distributions.

File: src/typescript/api/README.md Copy Chapter

This package lets you extend the Vicinae launcher using React and TypeScript.

Getting started

The recommend way to start developing a new extension is to read the docs.

Installation

Install the package:

npm install @vicinae/api

Versioning

The @vicinae/api package follows the same versioning as the main vicinae binary, since the API is always embedded in the binary.

CLI usage

The package exports the vici binary which is used to build and run extensions in development mode.

While convenience scripts are already provided in the boilerplate, you can still call the binary manually:

npx vici --help

# assuming vicinae is running
npx vici develop

npx vici build -o my/output/path

File: src/typescript/extension-manager/README.md Copy Chapter

The extension manager is a node process that can load and unload extensions at will.
It is spawned by the vicinae server command.

Communication is done through standard file descriptors:

• Standard output is used for the message scheme (protobuf)
• Standard error is used for debug messages

Note that since standard output is already assigned to the message scheme you should NOT use console.log but
console.error during development; otherwise you will end up interferring with the communication.

About versioning Copy Chapter

The version field of the package.json file is not meaningful. The manager is bundled with every vicinae release and thus shares the same version as the release it's built in.

File: src/typescript/raycast-api-compat/README.md Copy Chapter

This package is intended to provide a Raycast compatible entrypoint to the vicinae API (@vicinae/api).
It is only meant to be bundled as part of the full javascript bundle and is not published on npm, unlike the vicinae API.

This is used to provide raycast extension compatibility. When a Raycast extension imports something from @raycast/api, we route it
to this package instead at runtime.

As of now we mostly re-export stuff that belongs to the @vicinae/api package as many signatures are the exact same.

As we continue developping the vicinae SDK, we don't want to limit ourselves to what Raycast offers so using this package as a bridge
solves that problem. No matter what the @vicinae/api exports, we can expose a Raycast-compatible form.

File: src/typescript/README.md Copy Chapter

This directory contains the following typescript projects.
More information can be obtained on each project by navigating to their respective directories.

• extension-manager: a node process meant to be spawned by the main vicinae executable, ready to load and unload extension workers on-demand.
• @vicinae/api: the vicinae SDK used to build extensions, as published on npm
• @vicinae/raycast-api-compat: a private package that provides a raycast-compatible way to use the @vicinae/api package. It is a mere wrapper around it.

Integration with the build system

All the projects in this directory are bundled inside a single javascript file which is then executed at startup.

The @vicinae/api package is also published on npm on every release, and follows the main versioning scheme.

File: src/snippet/README.md Copy Chapter

vicinae snippet server

This library exports a snippet server that can register snippets and send notifications when expansion is required.

The main vicinae server will start the snippet server by calling itself with a specific set of arguments.

Communication between the main vicinae server and the snippet server is done using stdin and stdout. stderr is used for debug logs.

The vicinae server typically starts the snipet server, registers snippets that were persisted, and then starts listening for expansions.

The vicinae server receives an expansion notification when a given snippet is triggered, and shall populate the clipboard with whatever that specific snippet needs to be expanded to.

It then sends another request to the snippet server in order to inject ctrl+v or ctrl+shift+v at the cursor position.

Expansion is performed in vicinae because vicinae already has all the context required for expansion, and complex expansion types may require accessing vicinae data directly (focused window, active app, clipboard contents...).

For the snippet server to work as intended, relevant udev rules need to be enabled. In most cases, this is done through the vicinae installation process.

File: src/lib/xdgpp/README.md Copy Chapter

C++ library implementing various Freedesktop specifications.

This is in very early stage and is exclusively relied on by the Vicinae launcher. Breaking changes WILL occur without prior notice.

Use in your own project at your own risk.

Goals

The goal of this library is to provide high-level interfaces to deal with various specifications, such as the desktop entry one.

For now, this library (roughly) implements:

• mime-apps
• desktop-entry

Build and install

This is only if you care about dealing with this library on its own.
Otherwise, it is automatically compiled as part of the vicinae build process.

Build Copy Chapter

To build the library:

make static
# or, if you want a dynamic library:
make shared

Install Copy Chapter

make install

2. Official Technical Reference & Guides (vicinaehq/website) Copy Chapter

This is a Next.js project bootstrapped with create-next-app.

Getting Started Copy Chapter

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More Copy Chapter

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel Copy Chapter

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.