Manage Webapps (Vicinae Extension)

Create, edit, and delete Linux .desktop entries for web apps directly from Vicinae.

This extension is designed for workflows like:

• opening sites in app mode (--app=...)
• keeping one window per app
• focusing an existing app window instead of launching duplicates

Features

• Manage desktop entries from Vicinae UI
• Configurable browser command and arguments template
• Automatic favicon download for nicer launcher icons
• Per-app single-window mode
• Automatic window identity learning (no manual match value needed)
• Window-manager aware focusing for:
  • niri
  • hyprland
  • sway
  • i3
  • custom

Requirements

• Linux desktop
• Vicinae installed
• Node.js + npm (for building from source)
• jq (required for automatic window detection/focus logic)
• WM CLI for your selected backend:
  • niri for niri
  • hyprctl for hyprland
  • swaymsg for sway
  • i3-msg for i3

Install

1. Clone this repository.
2. Install dependencies:

npm install

3. Build the extension:

npm run build

4. Open Vicinae and run the command:

• Manage Webapps

If you are developing locally, use:

npm run dev

Initial Configuration (Vicinae Preferences)

Open extension preferences and set:

• Desktop Entries Directory
  • Default: ~/.local/share/applications
• Browser Command
  • Default: chromium-browser
• Browser Args Template
  • Default: --app={url}
  • Supported placeholders:
    • {url}
    • {origin}
    • {hostname}
• Window Manager
  • Default: niri
• Custom Focus Command
  • Used only when Window Manager = custom
  • Supports {match} and {mode} placeholders

Create Your First Webapp Entry

1. Open Manage Webapps.
2. Press Shift+Enter (or choose Create Desktop Entry).
3. Fill:

• Entry Name
• URL
• optional Comment
• browser command/template if different from defaults

4. Save.

The .desktop file will be written to your configured directory.

Single-Window Mode (How It Works)

Per entry, enable:

• Reuse and focus existing window if already open
• choose Match Strategy:
  • App ID
  • Class
  • Title
  • Any Field

Behavior:

1. First launch with single-window enabled:

• extension launches the app
• waits briefly for the new window
• auto-detects a match signature based on selected strategy
• saves it for future launches

2. Next launches:

• if a matching window exists, it is focused
• otherwise a new window is launched

If one strategy is unreliable for a specific site/browser combo, edit entry and try another strategy.

Useful Browser Template Examples

Chromium app mode:

--app={url}

Regular new window:

--new-window {url}

Profile-specific app window (example):

--profile-directory=Default --app={url}

Keyboard Shortcuts in List

• Enter: Edit selected entry
• Shift+Enter: Create new entry

Troubleshooting

Entry launches but does not focus existing window

• Ensure jq is installed
• Ensure your selected WM backend command exists (niri, hyprctl, swaymsg, i3-msg)
• Open entry settings and try a different Match Strategy
• Launch once after changing strategy so detection can relearn

Desktop icon is generic / favicon missing

• Some sites block favicon fetches or require auth
• Use Refresh Favicon action in the command
• If still missing, launcher falls back to generic browser icon

Desktop entry not showing in launcher menu

Run (if your environment needs it):

update-desktop-database ~/.local/share/applications

Custom Window Manager Backend

If built-in WM backends do not fit your setup:

1. Set Window Manager to custom
2. Provide Custom Focus Command

Your command should:

• attempt focus for the given {match} and {mode}
• exit 0 on success
• exit non-zero if no window matched

Notes

• Existing entries can be edited and re-saved to pick up newer launcher behavior.
• This project targets pragmatic Linux webapp launcher workflows via Vicinae.