## 1. Project Overview & Quickstart (vicinaehq/vicinae)

## File: README.md

<h1 align="center">**Vicinae**</h1>
  <h4 align="center">A focused launcher for your desktop</h4>
  
  
  



**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](https://docs.vicinae.com/clipboard)
- [text expander (snippets)](https://docs.vicinae.com/snippets)
- [file search](https://docs.vicinae.com/file-search)
- [browser tab switcher](https://docs.vicinae.com/browser-extension)
- [emoji picker](https://docs.vicinae.com/emoji)
- [calculator](https://docs.vicinae.com/calculator)
- [window switcher](https://docs.vicinae.com/window)
- font browser
- volume controller

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

- [React/Typescript extensions](https://docs.vicinae.com/extensions/introduction), compatible with the Raycast ecosystem. In-app integration with the [Vicinae store](https://www.vicinae.com/extensions) and the [Raycast store](https://www.raycast.com/store).
- [Script commands](https://docs.vicinae.com/scripts/getting-started), also compatible with the Raycast feature of the same name, with special Vicinae additions.
- [dmenu style menu creation](https://docs.vicinae.com/dmenu), the linux minimalist way!

## Documentation

Everything you need to know to get started with Vicinae is at [vicinae.com](https://vicinae.com). If you have any question, please feel free to come ask it on [discord](https://discord.gg/rP4ecD42p7)!

## Sponsors

### Gold sponsors



|  |
| --- |



### Silver Sponsors



| [](https://coderabbit.link/vicinaehq) |
| --- |



### Supporter sponsors



| [](https://github.com/jaredallard) |
| --- |



---

[And all our other amazing sponsors!](https://github.com/sponsors/vicinaehq#sponsors)

## Acknowledgments

Special thanks to the [Soulver](https://soulver.app?utm_source=vicinae&utm_medium=readme) team for allowing us to ship SoulverCore as the default calculator backend on macOS.

---

## File: extra/extension-boilerplate/assets/README.md

# Vicinae Extension

Congratulations on generating your new Vicinae extension!

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

```bash
npm install
npm run dev
```
If you want to build the production bundle, simply run:

```bash
npm run build
```

---

## File: extra/extension-boilerplate/README.md

# 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

# Building the AppImage

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

```bash
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

This package lets you extend the [Vicinae](https://docs.vicinae.com/) launcher using React and TypeScript.

[](https://npmjs.org/package/@vicinae/api)
[](https://npmjs.org/package/@vicinae/api)

# Getting started

The recommend way to start developing a new extension is to [read the docs](https://docs.vicinae.com/extensions/introduction).

# 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:

```bash
npx vici --help

# assuming vicinae is running
npx vici develop

npx vici build -o my/output/path
```

---

## File: src/typescript/extension-manager/README.md

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

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

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

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

# 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

C++ library implementing various [Freedesktop](https://specifications.freedesktop.org/) 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](https://specifications.freedesktop.org/mime-apps-spec/latest/)
- [desktop-entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/)

# 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

To build the library:

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

## Install

```bash
make install
```

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

This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).

## Getting Started

First, run the development server:

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

Open [http://localhost:3000](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`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.

## Learn More

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

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!

## Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.