ItzEmoji Modular Architecture

website·Indexed 30 days ago

https://docs.itzemoji.com

A modular NixOS configuration framework featuring a Rust-based TUI installer, custom NixOS images exported to 26 formats, and a declarative Neovim configuration built with NVF. The architecture utilizes nixosModules for system-level and homeManagerModules for user-level configuration.

Tokens: 6.9K
Snippets: 38
Records: 50
Agent score: 50%

What's inside ItzEmoji

Overview of the ItzEmoji NixOS configuration architecture
The ItzEmoji NixOS configuration is a modular setup designed to eliminate boilerplate (such as manual import lists or default.nix files). It is built on three core technologies:
- flake-parts: Structures Nix flake outputs as composable modules.
- import-tree: Automatically discovers and imports all .nix files within a directory tree.
- Home Manager: Manages user-level configurations declaratively alongside the system configuration.
Because of this architecture, any .nix file created under the modules/ directory is automatically loaded.
https://docs.itzemoji.com/getting-started
Use the nixos-dotfiles configuration
The nixos-dotfiles repository provides a modular NixOS configuration utilizing flake-parts and import-tree for zero-boilerplate module management.
```
# GitHub: https://github.com/ItzEmoji/nixos-dotfiles
# GitLab: https://gitlab.com/ItzEmoji/nixos-dotfiles
# Codeberg: https://codeberg.org/ItzEmoji/nixos-dotfiles
# Gitea: https://gitea.com/ItzEmoji/nixos-dotfiles
```
https://docs.itzemoji.com/repositories
Neovim configuration architecture and file structure
The configuration follows a flake-parts + import-tree pattern.
- modules/: Contains flake-parts modules for package builds, outputs, and formatting.
- conf/: Contains NVF configuration modules (vim options, plugins, keybindings) passed to nvf.lib.neovimConfiguration.
Key files include:
- conf/vim-options.nix: Core options (indentation, theme, statusline).
- conf/config/keybinds.nix: All keybindings.
- conf/config/ui.nix: UI plugins like Noice and devicons.
- conf/plugins/: Individual Nix files for plugins (e.g., languages.nix for LSP/Treesitter, snacks.nix for UI framework).
https://docs.itzemoji.com/neovim

Organize modules using the recommended directory structure

The dotfiles architecture uses a categorized directory structure to separate system-level (NixOS) and user-level (Home Manager) configurations. It is recommended to co-locate configuration files (e.g., .conf files) in the same directory as their corresponding .nix module to keep them self-contained.

modules/
├── nixosModules/
│   ├── bootloaders/        # Boot configuration (grub, systemd-boot)
│   ├── config/             # System config (fonts, nix-cache, home-manager)
│   ├── general/            # General system features (bluetooth, virtualisation)
│   ├── gui/
│   │   ├── desktops/       # Desktop environments (hyprland, plasma)
│   │   ├── displaymanagers/ # Display managers (ly, sddm)
│   │   └── stylix/         # System-wide theming
│   ├── programs/           # System programs (nh)
│   ├── services/           # System services (audio, printing, ssh, tailscale)
│   └── videoDrivers/       # GPU drivers (nvidia, base drivers)
├── homeManagerModules/
│   ├── cli/                # Shell tools (zsh, tmux, fzf, atuin, etc.)
│   ├── gui/                # Desktop apps (hyprland config, waybar, dunst, rofi)
│   ├── programs/           # GUI programs (kitty, foot, spicetify)
│   └── services/           # User services (ssh-agent)
└── packages/               # Package lists (dual-export nixos + HM)

Implement the Module Pattern for NixOS and Home Manager
The dotfiles architecture uses a two-layer structure for all configuration modules. Modules are registered as either nixosModules (system-level) or homeManagerModules (user-level). The outer layer receives flake-parts arguments, while the inner layer receives the actual NixOS or Home Manager module arguments (like config and pkgs).
```
{ ... }:                                      # 1. Outer: flake-parts module args
{
  flake.<moduleType>.<moduleName> =           # 2. Register into flake outputs
    { config, pkgs, ... }:                    #    Inner: NixOS/HM module args
    {
      # Your configuration here
    };
}
```
https://docs.itzemoji.com/creating-modules
NixOS Installer workflow overview
The installer provides a guided TUI wizard that executes the following sequence:
1. Clone Repository: Clones dotfiles to /tmp/nixos-dotfiles.
2. Select Host Preset: Pick a preset from modules/hosts/ or create a custom one.
3. Configure Modules: Select NixOS modules and system packages (Custom mode).
4. Create Users: Define usernames and secure passwords.
5. Select Per-User Modules: Select Home Manager modules and user package sets.
6. Disk Partitioning: Choose 'Full Disk' (EFI, Swap, Root) or 'Custom' layout.
7. Confirm and Install: Partitions disk, generates hardware config, writes files, and runs nixos-install --flake <path>#<hostname>.
8. Set Passwords: Sets root and user passwords via nixos-enter.
9. Complete: Reboot into the new system.
https://docs.itzemoji.com/installer
Organize configurations using Modular Architecture
The configuration system uses a modular architecture where every piece of configuration is treated as a standalone module. This allows for mixing and matching configurations based on the specific host requirements. System-level configurations are defined as nixosModules, while user-level configurations are defined as homeManagerModules.
https://docs.itzemoji.com/
Download or netboot custom NixOS images
Custom NixOS images are built and published as GitHub releases in the nixos-images repository (GitHub-only). These include ISOs, cloud images, VM images, containers, and netboot artifacts.
```
# Download the ISO
wget https://github.com/ItzEmoji/nixos-images/releases/latest/download/nixos-installer.iso

# Or netboot via iPXE
chain https://github.com/ItzEmoji/nixos-images/releases/latest/download/netboot.ipxe
```
https://docs.itzemoji.com/repositories
Run the NixOS TUI installer
The nixos-installer is a Rust-based TUI installer for NixOS compatible with any flake-based dotfiles repository. It manages disk partitioning, module selection, user creation, and executes nixos-install.
```
nix run github:ItzEmoji/nixos-installer
```
https://docs.itzemoji.com/repositories

Build NixOS Installer from source

The installer is written in Rust and can be built using Nix or Cargo.

# Build with Nix
nix build github:ItzEmoji/nixos-installer

# Build with Cargo
git clone https://github.com/ItzEmoji/nixos-installer.git
cd nixos-installer
cargo build --release

Manage configuration files in Home Manager modules
Depending on the requirement, use one of the following patterns to manage config files:
1. Raw Files: Use home.file."path".source for files that don't need Nix interpolation.
2. Structured TOML/JSON: Use builtins.fromTOML or builtins.fromJSON combined with builtins.readFile for programs with dedicated HM .settings options.
3. Inline Nix: Define attributes directly in Nix for maximum control (conditionals, package references).
```
# Raw file example
home.file.".config/tmux/tmux.conf".source = ./tmux.conf;

# Structured TOML example
programs.atuin.settings = builtins.fromTOML (builtins.readFile ./config.toml);

# Structured JSON example
programs.oh-my-posh.settings = builtins.fromJSON (builtins.readFile ./config.json);
```
https://docs.itzemoji.com/creating-modules
Boot NixOS via iPXE Netboot
Boot into an iPXE environment and chain-load the netboot script. The script automatically fetches the Linux kernel (bzImage) and initial ramdisk (initrd) from the GitHub release to boot the NixOS installer without a USB drive.
```
# Chain-load the netboot script
chain https://github.com/ItzEmoji/nixos-images/releases/latest/download/netboot.ipxe
```
https://docs.itzemoji.com/nixos-images