nixpkgs/docs/modules/home-manager/overview.md

# Home Manager Modules Overview

Overview of available Home Manager modules in m3ta-nixpkgs.

## Available Modules

### Core Modules

- [ports](./ports.md) - Port management across hosts

### CLI Modules (`cli/`)

- [zellij-ps](./cli/zellij-ps.md) - Zellij project switcher

### Coding Modules (`coding/`)

- [editors](./coding/editors.md) - Editor configurations

## Importing Modules

### Import All Modules

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];
}
```

### Import Specific Module

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.ports
    m3ta-nixpkgs.homeManagerModules.zellij-ps
  ];
}
```

### Import Category

```nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.cli.zellij-ps
    m3ta-nixpkgs.homeManagerModules.coding.editors
  ];
}
```

## Module Namespace

All Home Manager modules use the `m3ta.*` namespace:

```nix
# Port management
m3ta.ports = {
  enable = true;
  definitions = {dev-server = 3000;};
};

# CLI tools
m3ta.cli.zellij-ps = {
  enable = true;
};

# Coding tools
m3ta.coding.editors = {
  enable = true;
  neovim.enable = true;
};
```

## Module Categories

### Core

Essential modules for all users:

- **ports** - Port management with optional environment variable generation

### CLI (`cli/`)

Command-line interface tools and utilities:

- **zellij-ps** - Project switcher for Zellij terminal multiplexer

### Coding (`coding/`)

Development tools and configurations:

- **editors** - Editor configurations (Neovim, Zed, etc.)

## Integration Examples

### With NixOS

```nix
{config, ...}: {
  # NixOS modules
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  # Home Manager integration
  home-manager.users.myusername = {
    imports = [
      m3ta-nixpkgs.homeManagerModules.default
    ];

    m3ta.ports = {
      enable = true;
      definitions = {
        dev-server = 3000;
      };
      currentHost = config.networking.hostName;
    };
  };
}
```

### Standalone Home Manager

```nix
{config, pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];

  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
    };
    currentHost = "desktop";
  };

  m3ta.cli.zellij-ps = {
    enable = true;
  };

  m3ta.coding.editors = {
    enable = true;
    neovim.enable = true;
  };
}
```

## Module Locations

### Core

- `modules/home-manager/ports.nix` - Port management module

### CLI

- `modules/home-manager/cli/default.nix` - CLI module aggregator
- `modules/home-manager/cli/zellij-ps.nix` - Zellij project switcher

### Coding

- `modules/home-manager/coding/default.nix` - Coding module aggregator
- `modules/home-manager/coding/editors.nix` - Editor configurations

## Adding New Modules

### Core Module

1. Create: `modules/home-manager/my-module.nix`
2. Add to `modules/home-manager/default.nix`

### CLI Module

1. Create: `modules/home-manager/cli/my-tool.nix`
2. Add to `modules/home-manager/cli/default.nix`

### Coding Module

1. Create: `modules/home-manager/coding/my-tool.nix`
2. Add to `modules/home-manager/coding/default.nix`

### Module Template

```nix
{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.category.myModule;
in {
  options.m3ta.category.myModule = {
    enable = mkEnableOption "my module";
    # ... options
  };

  config = mkIf cfg.enable {
    # Configuration
  };
}
```

## Related

- [Using Modules Guide](../../guides/using-modules.md) - How to use modules
- [NixOS Modules](./nixos/overview.md) - System-level modules
- [Port Management Guide](../../guides/port-management.md) - Detailed port management