webapps: add module for declarative web application desktop entries #7917

i-am-logger · 2025-10-01T11:37:33Z

Description

This PR adds a new webapps module for Home Manager that allows users to declaratively configure web applications as desktop entries. This enables creating application launcher entries for web services like Gmail, Slack, Discord, GitHub, etc., with proper browser integration and desktop environment support.

Inspiration: This module was inspired by the webapps functionality in omarchy. Special thanks to @dhh for the inspiration and approach.

Features

Declarative Configuration: Define web applications with clean Nix syntax
Auto-Browser Detection: Automatically detects and uses available browsers (Chromium, Brave, Firefox)
App Mode Support: Creates proper --app= flags for Chromium-based browsers for true webapp experience
Icon Management: Supports both declarative icon packages and theme icon names
Desktop Integration: Creates proper .desktop entries that integrate with application launchers
MIME Type Support: Handles MIME types for protocol association (e.g., mailto: links)
Window Management: Sets StartupWMClass for proper application grouping

Usage Example

programs.webApps = {
  enable = true;
  apps = {
    gmail = {
      url = "https://mail.google.com";
      name = "Gmail";
      icon = "${pkgs.papirus-icon-theme}/share/icons/Papirus/64x64/apps/gmail.svg";
      categories = [ "Network" "Email" "Office" ];
      mimeTypes = [ "x-scheme-handler/mailto" ];
      startupWmClass = "gmail-webapp";
    };
    github = {
      url = "https://github.com";
      name = "GitHub";
      icon = "github";
      categories = [ "Development" "Network" ];
    };
  };
};

Checklist

Change is backwards compatible.
Code formatted with nix fmt.
Test cases updated/added - comprehensive test suite included.
Commit messages are formatted correctly.
Added myself as module maintainer.
Basic tests added covering various use cases.

Tests Included

Basic functionality test
Auto-detection of browsers
Explicit browser configuration
Custom options and extraOptions
Gmail example (real-world use case)

The module has been thoroughly tested and is working correctly with Hyprland + Rofi, creating proper desktop entries that appear in application launchers and launch web applications in app mode.

Special thanks to @dhh and the omarchy project for the inspiration!

khaneliman · 2025-10-05T02:51:17Z

modules/programs/webapps.nix

+  ...
+}:
+
+with lib;


Suggested change

with lib;

khaneliman · 2025-10-12T22:31:13Z

modules/programs/webapps.nix

+  cfg = config.programs.webApps;
+
+  # Type for a single web app
+  webAppOpts = types.submodule ({


Prefer in-lining submodule usage or scoping in a let block closer to usage.

khaneliman · 2025-10-12T22:33:22Z

modules/programs/webapps.nix

+      isChromiumBased = elem browserName [
+        "chromium"
+        "brave"
+        "google-chrome"
+        "google-chrome-stable"
+        "vivaldi"
+      ];
+
+      binary = "${toString browserPkg}/bin/${browserName}";
+    in
+    if isChromiumBased then
+      "${binary} --app=${escapeDesktopArg url} ${optionString}"
+    else if browserName == "firefox" then
+      "${binary} ${escapeDesktopArg url}" # Firefox doesn't support --app mode
+    else
+      # Fallback: assume chromium-based behavior
+      "${binary} --app=${escapeDesktopArg url} ${optionString}";
+
+  # Auto-detect browser if not explicitly set
+  detectedBrowser =
+    if cfg.browser != null then
+      cfg.browser
+    else if config.programs.chromium.enable && config.programs.chromium.package != null then
+      config.programs.chromium.package
+    else if config.programs.brave.enable && config.programs.brave.package != null then
+      config.programs.brave.package
+    else if config.programs.firefox.enable && config.programs.firefox.package != null then
+      config.programs.firefox.package
+    else
+      pkgs.chromium; # Default fallback


Might be cleaner to create an attrset used for configuring these default / known browsers instead of multiple if else if blocks

In my opinion we should make it so cfg.browser is type = types.package (i.e: not-nullable) and set an appropriate default in the module option. We should also document the default choice.

ambroisie · 2025-10-13T15:04:59Z

modules/programs/webapps.nix

+      name = mkOption {
+        type = types.nullOr types.str;
+        default = null;
+        description = "Name of the web application. If not provided, will be derived from the attribute name.";
+        example = "GitHub";
+      };


types.submodule can use a function to get the attribute name, this avoids the nullOr which doesn't really want null:

type = lib.types.attrsOf (lib.types.submodule ({ name, ... }: { // ... name = lib.mkOption { type = lib.types.str; default = name; description = "..."; }; // ... }));

ambroisie · 2025-10-13T15:07:09Z

modules/programs/webapps.nix

+          "Network"
+          "WebBrowser"
+        ];
+        description = "Categories in which the entry should be shown in application menus.";


Is there a canonical list of categories we can link to?

ambroisie · 2025-10-13T15:09:10Z

modules/programs/webapps.nix

+      # Desktop entries don't need shell escaping, just basic space escaping
+      escapeDesktopArg = arg: builtins.replaceStrings [ " " ] [ "\\ " ] (toString arg);
+
+      optionString = concatStringsSep " " (
+        mapAttrsToList (name: value: "--${name}=${escapeDesktopArg value}") extraOptions
+      );


Note: I feel like toGNUCommandLine should be able to be used in this circumstance. Perhaps a PR to add a way to customize the escaping function would be good.

ambroisie · 2025-10-13T15:10:14Z

modules/programs/webapps.nix

+      isChromiumBased = elem browserName [
+        "chromium"
+        "brave"
+        "google-chrome"
+        "google-chrome-stable"
+        "vivaldi"
+      ];
+
+      binary = "${toString browserPkg}/bin/${browserName}";
+    in
+    if isChromiumBased then
+      "${binary} --app=${escapeDesktopArg url} ${optionString}"
+    else if browserName == "firefox" then
+      "${binary} ${escapeDesktopArg url}" # Firefox doesn't support --app mode
+    else
+      # Fallback: assume chromium-based behavior
+      "${binary} --app=${escapeDesktopArg url} ${optionString}";


An isFirefoxBased filter would lead to less duplication.

ambroisie · 2025-10-13T15:11:36Z

modules/programs/webapps.nix

+      isChromiumBased = elem browserName [
+        "chromium"
+        "brave"
+        "google-chrome"
+        "google-chrome-stable"
+        "vivaldi"
+      ];
+
+      binary = "${toString browserPkg}/bin/${browserName}";
+    in
+    if isChromiumBased then
+      "${binary} --app=${escapeDesktopArg url} ${optionString}"
+    else if browserName == "firefox" then
+      "${binary} ${escapeDesktopArg url}" # Firefox doesn't support --app mode
+    else
+      # Fallback: assume chromium-based behavior
+      "${binary} --app=${escapeDesktopArg url} ${optionString}";
+
+  # Auto-detect browser if not explicitly set
+  detectedBrowser =
+    if cfg.browser != null then
+      cfg.browser
+    else if config.programs.chromium.enable && config.programs.chromium.package != null then
+      config.programs.chromium.package
+    else if config.programs.brave.enable && config.programs.brave.package != null then
+      config.programs.brave.package
+    else if config.programs.firefox.enable && config.programs.firefox.package != null then
+      config.programs.firefox.package
+    else
+      pkgs.chromium; # Default fallback


In my opinion we should make it so cfg.browser is type = types.package (i.e: not-nullable) and set an appropriate default in the module option. We should also document the default choice.

ambroisie · 2025-10-13T15:18:10Z

tests/modules/programs/webapps/custom-options.nix

+  config = {
+    programs.webApps = {
+      enable = true;
+      browser = pkgs.chromium;


Dummy package.

ambroisie · 2025-10-13T15:18:17Z

tests/modules/programs/webapps/explicit-browser.nix

+  config = {
+    programs.webApps = {
+      enable = true;
+      browser = pkgs.firefox;


Dummy package.

ambroisie · 2025-10-13T15:18:23Z

tests/modules/programs/webapps/gmail-example.nix

+{
+  programs.webApps = {
+    enable = true;
+    browser = pkgs.chromium;


Dummy package.

ambroisie · 2025-10-13T15:18:29Z

tests/modules/programs/webapps/package-icons.nix

+
+  programs.webApps = {
+    enable = true;
+    browser = pkgs.chromium;


Dummy package.

ambroisie · 2025-10-13T15:20:05Z

modules/programs/webapps.nix

+      };
+
+      extraOptions = mkOption {
+        type = types.attrs;


I'd use the usual attrsOf (oneOf [ str number boolean ]) type for command line options.

i-am-logger · 2025-10-13T18:19:53Z

Thanks for the review, will update it towards weekend hopefully as i'm traveling

i-am-logger force-pushed the feature/webapps-module branch 9 times, most recently from d8ba7b9 to d0b2c07 Compare October 1, 2025 12:41

webapps: add module for declarative web application desktop entries

c48be9e

i-am-logger force-pushed the feature/webapps-module branch from d0b2c07 to c48be9e Compare October 1, 2025 13:26

github-actions bot added the shell label Oct 1, 2025

Merge branch 'nix-community:master' into feature/webapps-module

bdb2582

github-actions bot removed the shell label Oct 3, 2025

github-actions bot added merge conflict and removed merge conflict labels Oct 12, 2025

khaneliman reviewed Oct 12, 2025

View reviewed changes

ambroisie reviewed Oct 13, 2025

View reviewed changes

Uh oh!

webapps: add module for declarative web application desktop entries #7917

Are you sure you want to change the base?

webapps: add module for declarative web application desktop entries #7917

Uh oh!

Conversation

i-am-logger commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Features

Usage Example

Checklist

Tests Included

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ambroisie Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

i-am-logger commented Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

i-am-logger commented Oct 1, 2025 •

edited

Loading

ambroisie Oct 13, 2025 •

edited

Loading