Existing NIXOS Setup Integration

[GendersGod]

Disclaimer: Im just a dude that doesn't know code and has an unhealthy obsession with NIXOS because youtube convinced me so:
There seems to be some dedicated folks that have put in a lot effort into porting caelestia to NIXOS. The documentation avaiable is poorly described for beginners of NIXOS and/or rely on a clean install of NIXOS. Lets face it, no one is trying to clean out their setup just to make room for this awesome bit of code, or troubleshoot the integration of a custom module into NIXOS. So here's how to properly integrate caelestia-cli and caelestia-shell into your existing NIXOS configs/flake. If you're an advanced user, I didn't make this for you. I simply made a guide. I DO NOT claim this as my own, credit is below.

Directory setup is as follows:

~/.dotfiles
      configuration.nix
      flake.nix
      modules
          caelestia
              default.nix
              path.txt
              shell.json

flake.nix

{
  description = "Hyprland + Caelestia Shell";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    caelestia-shell = {
      url = "github:caelestia-dots/shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, caelestia-shell, ... }@inputs:
    let
      system = "x86_64-linux";
      lib = nixpkgs.lib;
    in {
      nixosConfigurations.nixos = lib.nixosSystem {
        specialArgs = { inherit inputs system; };
        modules = [
          inputs.home-manager.nixosModules.default
          ./configuration.nix
          {
            nixpkgs.overlays = [
              (final: prev: {
                caelestia-shell = caelestia-shell.packages.${system}.caelestia-shell;
                caelestia-cli   = caelestia-shell.inputs.caelestia-cli.packages.${system}.caelestia-cli;
              })
            ];
          }
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.backupFileExtension = "backup";
            home-manager.users.{CHANGE ME TO YOUR USERNAME} = {
              imports = [
                ./modules/hm #CHANGE ME FOR UR SETUP
                ./modules/hyprland #CHANGE ME FOR UR SETUP
                ./modules/caelestia #CHANGE ME FOR UR SETUP 
              ];
            };
          }
        ];
      };
    };
}

My default.nix does normal Home-manager things. You declaritively manage your files in your dotfiles directory and it copies over to .local/state/caelestia and .config/caelestia as required by the module.
default.nix

{ config, pkgs, lib, ... }:

let
  caelestiaConfigDir = ./.;
in
{
  home.packages = with pkgs; [
    caelestia-shell
    caelestia-cli
  ];

  xdg.configFile."caelestia/shell.json".source =
    caelestiaConfigDir + "/shell.json";

  xdg.stateFile."caelestia/wallpaper/path.txt".source =
    caelestiaConfigDir + "/path.txt";
}

/home/{user}/.dotfiles/modules/caelestia/background.png
#path.txt will be the path to your desired background.
#Make it an impure path!!! The try hards can cry about it :D

shell.json I will not get into the setup of. There seems to be enough documentation and if youre following this guide, you likely dont care.

Here's mine:

{
    "appearance": {
        "anim": {
            "durations": {
                "scale": 1
            }
        },
        "font": {
            "family": {
                "material": "Material Symbols Rounded",
                "mono": "CaskaydiaCove NF",
                "sans": "Rubik"
            },
            "size": {
                "scale": 1
            }
        },
        "padding": {
            "scale": 1
        },
        "rounding": {
            "scale": 1
        },
        "spacing": {
            "scale": 1
        },
        "transparency": {
            "enabled": false,
            "base": 0.85,
            "layers": 0.4
        }
    },
    "general": {
        "apps": {
            "terminal": ["foot"],
            "audio": ["pavucontrol"]
        }
    },
    "background": {
        "desktopClock": {
            "enabled": false
        },
        "enabled": true,
        "visualiser": {
            "enabled": false,
            "autoHide": true,
            "rounding": 1,
            "spacing": 1
        }
    },
    "bar": {
        "clock": {
            "showIcon": true
        },
        "dragThreshold": 20,
        "entries": [
            {
                "id": "logo",
                "enabled": true
            },
            {
                "id": "workspaces",
                "enabled": true
            },
            {
                "id": "spacer",
                "enabled": true
            },
            {
                "id": "activeWindow",
                "enabled": true
            },
            {
                "id": "spacer",
                "enabled": true
            },
            {
                "id": "tray",
                "enabled": true
            },
            {
                "id": "clock",
                "enabled": true
            },
            {
                "id": "statusIcons",
                "enabled": true
            },
            {
                "id": "power",
                "enabled": true
            },
            {
                "id": "idleInhibitor",
                "enabled": false
            }
        ],
        "persistent": true,
        "showOnHover": true,
        "status": {
            "showAudio": false,
            "showBattery": true,
            "showBluetooth": true,
            "showKbLayout": false,
            "showNetwork": true
        },
        "tray": {
            "background": false,
            "recolour": false
        },
        "workspaces": {
            "activeIndicator": true,
            "activeLabel": "󰮯",
            "activeTrail": false,
            "label": "  ",
            "occupiedBg": false,
            "occupiedLabel": "󰮯",
            "perMonitorWorkspaces": true,
            "showWindows": true,
            "shown": 5
        }
    },
    "border": {
        "rounding": 25,
        "thickness": 10
    },
    "dashboard": {
        "enabled": true,
        "dragThreshold": 50,
        "mediaUpdateInterval": 500,
        "showOnHover": true
    },
    "launcher": {
        "actionPrefix": ">",
        "dragThreshold": 50,
        "vimKeybinds": false,
        "enableDangerousActions": false,
        "maxShown": 8,
        "maxWallpapers": 9,
        "specialPrefix": "@",
        "useFuzzy": {
            "apps": false,
            "actions": false,
            "schemes": false,
            "variants": false,
            "wallpapers": false
        },
        "showOnHover": false
    },
    "lock": {
        "recolourLogo": false
    },
    "notifs": {
        "actionOnClick": false,
        "clearThreshold": 0.3,
        "defaultExpireTimeout": 5000,
        "expandThreshold": 20,
        "expire": false
    },
    "osd": {
        "enabled": true,
        "enableBrightness": true,
        "enableMicrophone": false,
        "hideDelay": 2000
    },
    "paths": {
        "mediaGif": "root:/assets/bongocat.gif",
        "sessionGif": "root:/assets/kurukuru.gif",
        "wallpaperDir": "~/Pictures/Wallpapers"
    },
    "services": {
        "audioIncrement": 0.1,
        "defaultPlayer": "Spotify",
        "gpuType": "",
        "playerAliases": [
            { "from": "com.github.th_ch.youtube_music", "to": "YT Music" }
        ],
        "weatherLocation": "",
        "useFahrenheit": false,
        "useTwelveHourClock": false,
        "smartScheme": true,
        "visualiserBars": 45
    },
    "session": {
        "dragThreshold": 30,
        "vimKeybinds": false,
        "commands": {
            "logout": ["loginctl", "terminate-user", ""],
            "shutdown": ["systemctl", "poweroff"],
            "hibernate": ["systemctl", "hibernate"],
            "reboot": ["systemctl", "reboot"]
        }
    }
}

Finally add the app launcher to your Hyprland keybindings like so:

bind = MOD, KEY, global, caelestia:launcher
#real world example: bind = $mainMod, A, global, caelestia:launcher

I hope this is helpful to my copy pasta warriors out there. Im not going to maintain this tutorial. Im just a dude.
Credit:
https://github.com/soramanew
https://github.com/Markus328

Here's a copy of my configuration.nix, if you're a particulary struggling noob like myself. The main-user.nix import is straight from Vimjoyer 's home-manager setup on youtube. I've got some sddm lockscreen stuff in it too. I dunno, vibe code it out or something:

{ config, lib, pkgs, inputs, ... }:

{
  imports =
    [
      ./hardware-configuration.nix
      ./main-user.nix
      inputs.home-manager.nixosModules.default
    ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;
  boot.supportedFilesystems = [ "nfs" ];
  networking.networkmanager.enable = true;
  time.timeZone = "America/Los_Angeles";
  nixpkgs.config.allowUnfree = true;
  i18n.defaultLocale = "en_US.UTF-8";
  nix.settings.experimental-features = [ "nix-command" "flakes" ];
  programs.steam.enable = true;
  programs.steam.gamescopeSession.enable = true;
  services.pipewire.enable = true;
  programs.thunar.enable = true;
  services.openssh.enable = true;  

  programs.hyprland = {
    enable = true;
    withUWSM = true;
  };

  services.displayManager.sddm = {
    enable = true;
    package = pkgs.kdePackages.sddm;
    theme = "sddm-theme";
    extraPackages = with pkgs; [
      kdePackages.qtmultimedia
      kdePackages.qtsvg
      kdePackages.qtvirtualkeyboard
    ];
    wayland.enable = true;
  };

  home-manager = {
    extraSpecialArgs = { inherit inputs; };
    users = {
      "{user}" = import ./home.nix;
    };
  };

  users.users.{user} = {
    isNormalUser = true;
    description = "{user}";
    extraGroups = [ "networkmanager" "wheel" "plugdev" "i2c" "nfsusers" ];
    packages = with pkgs; [
      tree
    ];
  };


  environment.systemPackages = with pkgs; [
      (callPackage ./modules/hm/sddm/sddm.nix {
    theme = "sddm-theme";  # pass theme name if your derivation needs it
  })
    # {add ur pkgs, brother}
  ];

  system.stateVersion = "24.11";
}

edit: spelling
edit: added app launcher instruction

[Markus328]

Thanks for you help. I was actually creating a template repository for a very simple caelestia setup. Your config is good and more detailed, but I would recommend the caelestia hm module to take care of somethings.

I once was a NixOS newbie (I think im still) and I would appreciate more tutorials of how to do some basic things that basically no one says how to do. So, I plan yo mantain that repo (not published yet) to help some folks to install it in NixOS properly

[GendersGod]

Any time! And thank you, without your comments in other discussions I wouldn't have been able to use caelestia in the first place.

I agree but have very limited knowledge of Home-manager. I mostly use it to route config files with xdg. I'm excited to see your repo and will use when it's available.

[ThisManQ]

Thanks for you help. I was actually creating a template repository for a very simple caelestia setup. Your config is good and more detailed, but I would recommend the caelestia hm module to take care of somethings.

I once was a NixOS newbie (I think im still) and I would appreciate more tutorials of how to do some basic things that basically no one says how to do. So, I plan yo mantain that repo (not published yet) to help some folks to install it in NixOS properly

If you get this done. Plz let me know if u can

[ThisManQ]

Hey crazy timing. I just tried setting up caelestia on my own yesterday and managed to get it all working except the start menu launcher. Does your dot file fix this? Of so, I'll give it a try

[GendersGod]

If you followed this guide the app launcher is accessible by creating a Hyprland keybind, {keys}, global, caelestia:launcher. More info in other discussions.

[ThisManQ]

Cool! No I just did the caelestia setup on my own but it isn't perfect. Gonna adjust with ur dot files and try the keybind. Does mouse hover work for u? Or only keybind?

[GendersGod]

The keybind. I never attempted to enable the hover feature for the app launcher, I prefer it as is. My guess would be shell.json.

Credit goes to Markus328, these are his dotfiles, I only made slight adjustments and assembled this guide.

[Markus328]

I confess my dotfiles are quite confusious and I don't maintain that anymore. Someday I may rewrite them from scratch

[ThisManQ]

I just ran nix flake update just now and now i cant build my system due to celestia. Just a heads up

[GendersGod]

The only packages on my setup related to QT and QML are: kdePackages.qtmultimedia
kdePackages.qtsvg
kdePackages.qtvirtualkeyboard
Perhaps that is leading to the rebuild discrepancy

Edit: you could additionally add: qt6.qtbase. to your packages. I use SDDM which is also QT/QML based so perhaps i have some dependancies covered from that install. Your input would be appreaciated and I'll add it to the guide.

[Markus328]

This is a issue from the nix package of caelestia-shell. Not sure when it ocurred but I just opened a PR to fix this