### Configure Autostart Commands

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Specify a list of commands to be executed once when Hyprland starts. Ensure commands are correctly formatted strings.

```nix
{ ... }:
{
  programs.nixhypr.autostart = [
    "waybar"
    "dunst"
    "nm-applet --indicator"
    "wl-paste --type text --watch cliphist store"
  ];
}
```

--------------------------------

### Home Manager Integration Example

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Integrate nixhypr with Home Manager by adding it to your flake inputs and modules. This automatically generates `hyprland.lua` in the correct configuration directory.

```nix
# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    nixhypr.url = "github:youruser/nixhypr";
  };

  outputs = { nixpkgs, home-manager, nixhypr, ... }:
    {
      homeConfigurations.alice = nixpkgs.lib.homeManagerConfiguration {
        pkgs = nixpkgs.legacyPackages.x86_64-linux;
        modules = [
          nixhypr.homeManagerModules.default
          ./hyprland.nix
        ];
      };
    };
}

```

```nix
# hyprland.nix
{ ... }:
{
  programs.nixhypr = {
    enable = true;
    # package = hyprland.packages.x86_64-linux.hyprland; # optional
  };
}
# Result: ~/.config/hypr/hyprland.lua is created automatically.

```

--------------------------------

### Standalone mkHyprlandConfig Example

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Use `nixhypr.lib.mkHyprlandConfig` to generate `hyprland.lua` outside of Home Manager. This returns a derivation containing the configuration file.

```nix
# in a flake output or derivation
let
  config = nixhypr.lib.mkHyprlandConfig { inherit pkgs; } {
    programs.nixhypr.settings = {
      general.border_size = 2;
      decoration.rounding = 8;
    };
    programs.nixhypr.autostart = [ "waybar" ];
  };
in
  # config is a derivation; config/hyprland.lua is the generated file
  config
# $ cat result/hyprland.lua
# hl.config({
#   decoration = { rounding = 8, },
#   general = { border_size = 2, },
# })
# hl.exec_cmd("waybar")

```

--------------------------------

### Keybinding Examples in nixhypr

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Define keybindings in nixhypr for executing commands, calling Hyprland dispatchers, using dispatchers with arguments, defining raw Lua functions, or setting keybinding options.

```nix
# run a command
{ keys = ["SUPER" "Return"]; exec = "kitty"; }

# call a hyprland dispatcher
{ keys = ["SUPER" "q"]; action = "window.close"; }

# dispatcher with arguments
{ keys = ["SUPER" "1"]; action = "focus"; args = { workspace = 1; }; }

# raw lua function
{ keys = ["SUPER" "f"]; lua = "function() print('hello') end"; }

# bind options
{ keys = ["SUPER" "l"]; action = "window.close"; options = { locked = true; }; }
```

--------------------------------

### Home Manager Integration with nixhypr

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Integrate nixhypr into your Home Manager configuration by adding it as a flake input and importing the default module. This setup allows you to define Hyprland settings within your Nix configuration.

```nix
{ 
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
    nixhypr.url = "github:youruser/nixhypr";
  };

  outputs = { nixpkgs, nixhypr, ... }:
    { 
      homeConfigurations.myuser = nixpkgs.lib.homeManagerConfiguration {
        # ...
        modules = [
          nixhypr.homeManagerModules.default
          ./hyprland.nix
        ];
      };
    };
}
```

--------------------------------

### Configure Per-Device Input Settings in Hyprland with Nix

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Customize input device settings for Hyprland, such as sensitivity and keyboard layout, using Nix. Each device configuration is directly translated to `hl.device()` calls.

```nix
{ ... }:
{
  programs.nixhypr.devices = [
    {
      name         = "logitech-g502";
      sensitivity  = -0.5;
      accel_profile = "flat";
    }
    {
      name          = "at-translated-set-2-keyboard";
      kb_layout     = "us,de";
      kb_options    = "grp:alt_shift_toggle";
    }
  ];
}
```

```lua
# hl.device({accel_profile = "flat", name = "logitech-g502", sensitivity = -0.5,})
# hl.device({kb_layout = "us,de", kb_options = "grp:alt_shift_toggle", name = "at-translated-set-2-keyboard",})
```

--------------------------------

### Monitor Configuration

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Configure monitors using `programs.nixhypr.monitors`. Each entry in the list defines a monitor's output, mode, position, scale, and optional extra settings. Minimal configuration only requires the `output`.

```nix
{ ... }:
{
  programs.nixhypr.monitors = [
    {
      output   = "DP-1";
      mode     = "2560x1440@144";
      position = "0x0";
      scale    = "1";
    }
    {
      output   = "HDMI-A-1";
      mode     = "1920x1080@60";
      position = "2560x0";
      scale    = "1";
      extra    = { transform = 0; };  # passed through verbatim
    }
    {
      output = "eDP-1";  # minimal — only output required
    }
  ];
}
# Generated:
# hl.monitor({mode = "2560x1440@144", output = "DP-1", position = "0x0", scale = "1",})

```

--------------------------------

### Run VM Integration Test

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Execute a full VM integration test that boots Hyprland and verifies the generated configuration. This test is available on x86_64-linux with KVM.

```bash
just vm-test
```

--------------------------------

### Enter Nix Development Shell

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Use this command to enter the development environment provided by Nix. Alternatively, 'direnv' can be used for environment management.

```bash
nix develop
```

--------------------------------

### Define Binary Permission Rules

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Set rules for binary permissions, specifying the binary path or regex, the type of permission (e.g., screenshot, input), and whether to allow or deny it. This is useful for security.

```nix
{ ... }:
{
  programs.nixhypr.permissions = [
    { binary = "/usr/bin/grim";   type = "screenshot"; allow = "allow"; }
    { binary = "/usr/bin/wlroots-input"; type = "input"; allow = "deny"; }
  ];
}
```

--------------------------------

### Configure Touchpad/Touchscreen Gestures

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Define touchpad or touchscreen gestures by specifying the number of fingers, direction, and the action to perform. Actions can include switching workspaces or executing commands.

```nix
{ ... }:
{
  programs.nixhypr.gestures = [
    { fingers = 3; direction = "l"; action = "workspace +1"; }
    { fingers = 3; direction = "r"; action = "workspace -1"; }
    { fingers = 4; direction = "u"; action = "exec"; exec = "rofi -show drun"; }
  ];
}
```

--------------------------------

### Hyprland Configuration in nixhypr

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Define Hyprland settings, environment variables, monitors, keybindings, and autostart applications using nixhypr's structured options. This configuration is then compiled into `hyprland.lua`.

```nix
{ ... }:
{
  programs.nixhypr = {
    enable = true;

    settings = {
      general = {
        border_size = 2;
        gaps_in = 5;
        gaps_out = 10;
      };
      decoration = {
        rounding = 10;
      };
      input = {
        kb_layout = "us";
        follow_mouse = 1;
      };
    };

    env = {
      XCURSOR_SIZE = "24";
    };

    monitors = [
      {
        output = "DP-1";
        mode = "2560x1440@144";
        position = "0x0";
        scale = "1";
      }
    ];

    binds = [
      { keys = ["SUPER" "q"]; action = "window.close"; }
      { keys = ["SUPER" "Return"]; exec = "kitty"; }
      { keys = ["SUPER" "1"]; action = "focus"; args = { workspace = 1; }; }
    ];

    autostart = ["waybar" "dunst"];
  };
}
```

--------------------------------

### Individual Nix Build Checks

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Provides commands to build specific Nix check targets, allowing for granular testing of different components like toLua serialization, module evaluation, typechecking, and VM boot tests.

```shell
nix build .#checks.x86_64-linux.toLua
```

```shell
nix build .#checks.x86_64-linux.config
```

```shell
nix build .#checks.x86_64-linux.typecheck
```

```shell
nix build .#checks.x86_64-linux.vm
```

--------------------------------

### Run Common Commands with Just

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

A collection of common development tasks available through the 'just' command. These include formatting, linting, testing, and type checking.

```bash
just fmt        # format all files
```

```bash
just lint       # run statix + deadnix
```

```bash
just test       # build and run tests
```

```bash
just typecheck  # validate generated lua against hyprland type stubs
```

```bash
just check      # run all checks (tests + formatting + typecheck)
```

--------------------------------

### Format Nix Files

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Runs the code formatter on all Nix files in the project. Ensure your Nix code adheres to consistent style guidelines.

```shell
just fmt
```

--------------------------------

### Global Hyprland Settings

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Configure global Hyprland settings using `programs.nixhypr.settings`. This attrset is serialized into a single `hl.config({...})` call. Null values are filtered out.

```nix
{ ... }:
{
  programs.nixhypr.settings = {
    general = {
      border_size = 2;
      gaps_in    = 5;
      gaps_out   = 10;
    };
    decoration = {
      rounding = 10;
      shadow.offset = { __raw = "hl.Vec2(5, 5)"; }; # raw Lua value
    };
    input = {
      kb_layout    = "us";
      follow_mouse = 1;
      sensitivity  = 0.0;  # float: emitted as 0.0 (not 0.000000)
    };
    misc.disable_splash_rendering = true;
    experimental = null; # filtered out — not emitted
  };
}
# Generated:
# hl.config({
#   decoration = {
#     rounding = 10,
#     shadow = { offset = hl.Vec2(5, 5), },
#   },
#   general = { border_size = 2, gaps_in = 5, gaps_out = 10, },
#   input = { follow_mouse = 1, kb_layout = "us", sensitivity = 0.0, },
#   misc = { disable_splash_rendering = true, },
# })

```

--------------------------------

### Run All Checks

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Combines tests and formatting checks to ensure the project meets all quality and style standards. This is a comprehensive check before committing or merging changes.

```shell
just check
```

--------------------------------

### Define Hyprland Window, Workspace, and Layer Rules with Nix

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Apply custom rules to windows, workspaces, and layers in Hyprland using Nix. Rules are passed directly to Hyprland's rule functions, allowing configuration of properties like opacity, floating, size, default workspace, and blur.

```nix
{ ... }:
{
  programs.nixhypr.rules = {
    window = [
      { match = { class = "^firefox$"; };  opacity = 0.95; }
      { match = { class = "^pavucontrol$"; }; float = true; size = "800 600"; }
    ];
    workspace = [
      { workspace = "1"; default = true; }
      { workspace = "special:scratch"; on-created-empty = "kitty"; }
    ];
    layer = [
      { match = { namespace = "^waybar$"; }; blur = true; }
    ];
  };
}
```

```lua
# hl.window_rule({match = {class = "^firefox$",}, opacity = 0.95,})
# hl.window_rule({float = true, match = {class = "^pavucontrol$",}, size = "800 600",})
# hl.workspace_rule({default = true, workspace = "1",})
# hl.workspace_rule({"on-created-empty" = "kitty", workspace = "special:scratch",})
# hl.layer_rule({blur = true, match = {namespace = "^waybar$",},})
```

--------------------------------

### Configure Hyprland Animations and Curves with Nix

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Define custom animation curves (bezier and spring) and apply them to Hyprland's animations using Nix. Bezier curves require `points`, while spring curves need `mass`, `stiffness`, and `dampening`.

```nix
{ ... }:
{
  programs.nixhypr.animations = {
    curves = {
      smooth = {
        type   = "bezier";
        points = [ 0.05 0.9 0.1 1.0 ];
      };
      bouncy = {
        type      = "spring";
        mass      = 1;
        stiffness = 180;
        dampening = 12;
      };
    };
    animations = [
      { leaf = "windows"; enabled = true; speed = 6;   bezier = "smooth"; style = "slide"; }
      { leaf = "fade";    enabled = true; speed = 3;   bezier = "smooth"; }
      { leaf = "border";  enabled = true; spring = "bouncy"; }
    ];
  };
}
```

```lua
# hl.curve("smooth", {points = {0.05, 0.9, 0.1, 1.0,},})
# hl.curve("bouncy", {dampening = 12, mass = 1, stiffness = 180,})
# hl.animation({bezier = "smooth", enabled = true, leaf = "windows", speed = 6, style = "slide",})
# hl.animation({bezier = "smooth", enabled = true, leaf = "fade", speed = 3,})
# hl.animation({enabled = true, leaf = "border", spring = "bouncy",})
```

--------------------------------

### Define Hyprland Keybindings with Nix

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Configure custom keybindings for Hyprland using Nix. Supports executing shell commands, calling dispatcher actions with or without arguments, and defining raw Lua functions. Options like `locked` and `repeating` can be specified.

```nix
{ ... }:
{
  programs.nixhypr.binds = [
    # execute a shell command
    { keys = ["SUPER" "Return"]; exec = "kitty"; }

    # call a dispatcher with no arguments
    { keys = ["SUPER" "q"]; action = "window.close"; }

    # dispatcher with structured arguments
    { keys = ["SUPER" "1"]; action = "focus"; args = { workspace = 1; }; }

    # raw Lua function
    { keys = ["SUPER" "p"]; lua = "function() print('hello from nix') end"; }

    # bind flag: locked = true means works on locked screens
    { keys = ["SUPER" "l"]; action = "session.lock"; options = { locked = true; }; }

    # repeating bind (held key fires continuously)
    { keys = ["SUPER" "Right"]; action = "focus"; args = { direction = "r"; };
      options = { repeating = true; }; }
  ];
}
```

```lua
# hl.bind("SUPER + Return", hl.dsp.exec_cmd("kitty"))
# hl.bind("SUPER + q", hl.dsp.window.close())
# hl.bind("SUPER + 1", hl.dsp.focus({workspace = 1,}))
# hl.bind("SUPER + p", function() print('hello from nix') end)
# hl.bind("SUPER + l", hl.dsp.session.lock(), {locked = true,})
# hl.bind("SUPER + Right", hl.dsp.focus({direction = "r",}), {repeating = true,})
```

--------------------------------

### Standalone Nix Configuration Derivation

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Generate a Hyprland config derivation directly using `nixhypr.lib.mkHyprlandConfig` if not using Home Manager. This function takes Nixpkgs and your configuration as arguments.

```nix
let
  config = nixhypr.lib.mkHyprlandConfig { inherit pkgs; } {
    programs.nixhypr = {
      settings = { ... };
      binds = [ ... ];
    };
  };
in
  # config is a derivation containing hyprland.lua
  config
```

--------------------------------

### Enter Nix Development Shell

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Use `nix develop` to enter the development shell, which provides access to development tools and environments. This command is typically used with direnv for automatic environment loading.

```bash
# enter the dev shell (or use direnv with .envrc)
nix develop
```

--------------------------------

### Environment Variables Configuration

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Set environment variables for Hyprland using `programs.nixhypr.env`. Each entry is emitted as `hl.env("KEY", "value")` after `hl.config`.

```nix
{ ... }:
{
  programs.nixhypr.env = {
    XCURSOR_SIZE        = "24";
    QT_QPA_PLATFORMTHEME = "qt5ct";
    MOZ_ENABLE_WAYLAND  = "1";
  };
}
# Generated:
# hl.env("XCURSOR_SIZE", "24")
# hl.env("QT_QPA_PLATFORMTHEME", "qt5ct")
# hl.env("MOZ_ENABLE_WAYLAND", "1")

```

--------------------------------

### Extra Lua Configuration with `extraLua`

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Append arbitrary Lua code to the end of the generated `hyprland.lua` file using the `extraLua` option for custom logic or configurations not covered by nixhypr's options.

```nix
{
  extraLua = ''
    print("config loaded")
  '';
}
```

--------------------------------

### Serialize Nix Values to Lua using `toLua` and `toLuaAt`

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Utilize `nixhyprLib.toLua` and `nixhyprLib.toLuaAt` for low-level serialization of Nix data structures into Lua-compatible strings. `toLua` serializes at depth 0, while `toLuaAt` allows specifying an indentation depth for embedding.

```nix
# Use in your own flake or module
let
  nixhyprLib = import "${nixhypr}/lib" { inherit lib; };
  inherit (nixhyprLib) toLua toLuaAt;
in {
  # Primitives
  # toLua null          => "nil"
  # toLua true          => "true"
  # toLua 42            => "42"
  # toLua 3.14          => "3.14"
  # toLua "hello"       => "\"hello\""
  # toLua "a\"b"        => "\"a\\\"b\""

  # Collections
  # toLua []            => "{}"
  # toLua [1 2 3]       => "{\n  1,\n  2,\n  3,\n}"
  # toLua { x = 1; }   => "{\n  x = 1,\n}"

  # Null filtering
  # toLua { a = 1; b = null; }  => "{\n  a = 1,\n}"

  # Non-identifier keys use bracket syntax
  # toLua { "some-key" = true; }  => "{\n  [\"some-key\"] = true,\n}"
  # toLua { "end" = 1; }          => "{\n  [\"end\"] = 1,\n}"

  # Raw Lua passthrough
  # toLua { __raw = "function() end"; }  => "function() end"

  # toLuaAt for embedding at indentation depth 2
  # toLuaAt 2 { x = 1; }  =>  "{\n      x = 1,\n    }"

  example = toLua {
    general = { border_size = 2; gaps_in = 5; };
    input.kb_layout = "us";
  };
  # => "{\n  general = {\n    border_size = 2,\n    gaps_in = 5,\n  },\n  input = {\n    kb_layout = \"us\",\n  },\n}"
}
```

--------------------------------

### Run Unit Tests

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Executes unit tests, including toLua serialization, config module evaluation, and Lua typechecking. This ensures the core logic and configuration parsing are functioning correctly.

```shell
just test
```

--------------------------------

### Generated Hyprland Lua Configuration

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

The output `hyprland.lua` file generated by nixhypr, demonstrating how Nix options are translated into Lua code for Hyprland.

```lua
hl.config({
  decoration = {
    rounding = 10,
  },
  general = {
    border_size = 2,
    gaps_in = 5,
    gaps_out = 10,
  },
  input = {
    follow_mouse = 1,
    kb_layout = "us",
  },
})
hl.env("XCURSOR_SIZE", "24")
hl.monitor({
  mode = "2560x1440@144",
  output = "DP-1",
  position = "0x0",
  scale = "1",
})
hl.bind("SUPER + q", hl.dsp.window.close())
hl.bind("SUPER + Return", hl.dsp.exec_cmd("kitty"))
hl.bind("SUPER + 1", hl.dsp.focus({
  workspace = 1,
}))
hl.exec_cmd("waybar")
hl.exec_cmd("dunst")

```

--------------------------------

### Run Static Linters

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Executes static linters, specifically statix and deadnix, to check for potential issues and enforce code quality in Nix files.

```shell
just lint
```

--------------------------------

### Typecheck Hyprland Lua File

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Directly typecheck a specific 'hyprland.lua' configuration file using the provided script. Ensure the script path and the Lua file path are correct.

```bash
./scripts/typecheck.sh path/to/hyprland.lua
```

--------------------------------

### Typecheck Hyprland Lua Configuration

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Validates a generated hyprland.lua file against Hyprland's official type stubs using a provided script. This helps catch type errors in your configuration.

```shell
./scripts/typecheck.sh /path/to/hyprland.lua
```

--------------------------------

### Embed Raw Lua Expressions with `__raw`

Source: https://context7.com/karol-broda/nixhypr/llms.txt

Replace Nix values with `{ __raw = "..."; }` to emit Lua expressions directly. This is useful for values that cannot be easily represented as Nix types, like function calls or complex literals.

```nix
{ ... }:
{
  programs.nixhypr.settings = {
    decoration.shadow.offset = { __raw = "hl.Vec2(5, 5)"; };
    decoration.shadow.color  = { __raw = "0xff1a1a2e"; };
  };

  programs.nixhypr.binds = [
    {
      keys = ["SUPER" "z"];
      # inline raw lua as the dispatcher
      lua = ''
        function()
          local wins = hl.get_clients()
          hl.dsp.focus({ class = wins[1].class })()
        end
      '';
    }
  ];
}
```

--------------------------------

### Raw Lua Escape Hatch with `__raw`

Source: https://github.com/karol-broda/nixhypr/blob/master/README.md

Use the `__raw` attribute to insert raw Lua code directly into values where expected, such as for complex types like `hl.Vec2`.

```nix
{
  settings = {
    decoration.shadow.offset = { __raw = "hl.Vec2(5, 5)"; };
  };
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.