DOCSEARCHbyAlgolia
Submit Docs

niri-flake

repository·main·Indexed 21 days ago

https://github.com/sodiboo/niri-flake

A Nix flake providing packages for niri, a scrollable-tiling Wayland compositor. It includes NixOS and Home Manager modules for declarative configuration, build-time validation via niri schema, and integration with Stylix. The flake provides stable and unstable versions, a dedicated binary cache via Cachix, and a nixpkgs overlay to ensure dependency compatibility with mesa.

Tokens
13.3K
Snippets
34
Records
70
Agent score
72%

What's inside niri-flake

  1. How layer rules work in niri

    main

    Layer rules allow you to apply settings to specific layer surfaces (like bars, shells, or popups) based on matching criteria. Rules are processed in order, and non-null values overwrite values from previous matching rules.

    Matching Logic

    A layer rule matches if:

    1. Matches: Any rule in layer-rules.*.matches successfully matches the surface. If matches is empty, it matches everything.
    2. Excludes: No rule in layer-rules.*.excludes matches the surface.

    Match Rule Fields

    Each match rule can use:

    • namespace: A regular expression to match against the surface's namespace.
    • at-startup: A boolean. If true, matches surfaces opened within the first 60 seconds of niri starting (e.g., via spawn-at-startup). If false, matches surfaces opened after 60 seconds.

    Rule Inheritance

    Rules are applied sequentially. If a field in a rule is null, it inherits the value from the previous applicable rule. If a field is non-null, it overwrites the previous value.

  2. Use decorations with colors and gradients

    main

    Niri decorations (like borders and focus rings) use the <decoration> type, which accepts either a solid color or a linear gradient.

    Solid Colors

    Use a CSS color value (e.g., "#C0FFEE", "rgb(255 0 0)", or "sandybrown"). Supported non-standard functions include hwba(), hsv(), and hsva().

    Gradients

    Use a linear gradient approximating CSS linear-gradient().

    • from: The starting <color>.
    • angle: The angle in degrees, measured clockwise from a bottom-to-top gradient.
    • in': The colorspace for interpolation. Options include "srgb", "srgb-linear", "oklab", "oklch shorter hue", "oklch longer hue", "oklch increasing hue", and "oklch decreasing hue". (Note: the key is in' because in is a reserved keyword in Nix).

  3. Configure niri window rules

    main

    Window rules allow you to apply specific settings to windows based on matching criteria. Rules are processed in order, and the last matching rule wins (non-null values overwrite previous ones).

    How Matching Works

    Each rule contains a list of matches and excludes.

    1. matches: A window is 'considered' if it matches all rules in the matches list. If matches is empty, all windows are considered.
    2. excludes: If a window matches any rule in the excludes list, it is rejected from the current rule.

    A rule applies if the window is 'considered' AND not 'excluded'.

    Match Criteria

    • app-id: A regular expression matching the window's app id.
    • title: A regular expression matching the window's title.
    • at-startup: Matches if the window was opened within the first 60 seconds of niri starting up.

    Rule Inheritance

    Rules inherit values from previous rules. If a field in a rule is null, it retains the value from the previous applicable rule. If a field is non-null, it overwrites the previous value.

    programs.niri.settings.window-rules = [
  {
    # Match all windows with 'Firefox' in the title
    matches = [{ title = ".*Firefox.*"; }];
    # Apply a specific setting
    floating = true;
  }
  {
    # Match specific app-id
    matches = [{ app-id = "kitty"; }];
    # Exclude windows that are already floating
    excludes = [{ floating = true; }];
    # Set tiling for kitty
    floating = false;
  }
];

  4. How niri configuration generation works

    main

    Niri configuration is managed through two primary methods in homeModules.config:

    1. programs.niri.settings: The recommended Nix-native way. You define settings using Nix submodules, and the module generates a valid KDL config.
    2. programs.niri.config: Allows you to provide a raw string or a kdl document.

    Warning: If you use programs.niri.config, it completely overrides everything defined in programs.niri.settings.

    If you use programs.niri.config, the module will run niri validate on the content before committing it to ensure your system doesn't fail to build due to an invalid configuration.

  5. Protect sensitive windows from screen capture

    main

    The programs.niri.settings.window-rules.*.block-out-from option allows you to hide window contents from specific capture methods. This is critical for privacy when using password managers or private chats.

    Options:

    • null: No protection. The window is visible to everything.
    • "screencast": Blocks the org.freedesktop.portal.ScreenCast interface (used by OBS). Note: The window may still be visible to tools using the wlr-screencopy protocol (like grim).
    • "screen-capture": Blocks both ScreenCast and wlr-screencopy. This is the most secure setting and ensures the window is never visible to external capture tools, though it may also affect how some screenshot tools display the window.
    block-out-fromScreenCast (OBS)screencopy (grim)screenshot (niri)
    nullyesyesyes
    "screencast"noyesyes
    "screen-capture"nonoyes

    Recommendation for Streamers: Use block-out-from = "screen-capture"; to prevent accidental leaks via wlr-screencopy tools that might show a preview during a stream.

    programs.niri.settings.window-rules = [
  {
    match = "class=password-manager";
    block-out-from = "screen-capture";
  }
];

  6. Quickstart: Run niri from the flake

    main

    You can try out niri immediately without a full installation by using nix run. To use the latest commit from the main branch (unstable), use the #niri-unstable suffix.

    # Run the stable version
nix run github:sodiboo/niri-flake

# Run the unstable version (latest commit to main)
nix run github:sodiboo/niri-flake#niri-unstable

  7. Configure environment for Electron applications

    main

    To ensure Electron applications (like VS Code) run correctly with Wayland, set the NIXOS_OZONE_WL environment variable.

    Note: You must start niri using the niri-session binary for these environment variables to be applied correctly.

    { programs.niri.settings.environment."NIXOS_OZONE_WL" = "1"; }

  8. Configure Waybar for niri

    main

    When using Waybar with niri, you should set the layer to top to ensure it remains visible over windows, and enable the systemd service to ensure reliable restarts.

    {
  programs.waybar.settings.mainBar.layer = "top";
  programs.waybar.systemd.enable = true;
}

  9. Configure niri on NixOS

    main

    Use the nixosModules.niri module to manage niri on NixOS. This module automatically enables a binary cache to speed up installation and, if configured, integrates with home-manager and stylix.

    # Example NixOS configuration snippet
programs.niri = {
  enable = true;
  package = pkgs.niri-unstable; # Options: pkgs.niri, pkgs.niri-stable, pkgs.niri-unstable
};

# Enable the binary cache to avoid long build times
niri-flake.cache.enable = true;

  10. Use the niri binary cache with cachix

    main

    To avoid building niri locally, you can use the hosted binary cache. The cache provides builds for niri-stable and niri-unstable for nixos-unstable and nixos-25.05 on x86_64-linux.

    cachix use niri

  11. Use niri-unstable via NixOS or Home Manager

    main

    Both niri.nixosModules.niri and niri.homeModules.niri allow you to switch to the unstable version of niri by setting programs.niri.package to pkgs.niri-unstable. You must also include the overlays.niri overlay to make the package available.

    { inputs, pkgs, ... }: {
  nixpkgs.overlays = [ inputs.niri.overlays.niri ];
  programs.niri.package = pkgs.niri-unstable;
}

  12. Integrate niri with Stylix

    main

    The niri.homeModules.stylix module allows Stylix to manage niri's appearance (active/inactive border colors, layout.border, and xcursor themes).

    Important: To use Stylix, you must not set programs.niri.config, as setting config will override the settings applied by Stylix via programs.niri.settings.