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

# ports Home Manager Module

Port management module for Home Manager.

## Overview

This module provides centralized port management for user-level services, similar to the NixOS version but with additional support for generating environment variables.

See [Port Management Guide](../../guides/port-management.md) for detailed usage.

## Quick Start

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;

    # Define default ports
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };

    # Host-specific overrides
    hostOverrides = {
      laptop = {
        vite = 5174;
      };
    };

    # Current host
    currentHost = "desktop";

    # Generate environment variables (Home Manager only)
    generateEnvVars = true;
  };
}
```

## Module Options

### `m3ta.ports.enable`

Enable port management.

- Type: `boolean`
- Default: `false`

### `m3ta.ports.definitions`

Default port definitions.

- Type: `attrsOf int`
- Default: `{}`

Example:

```nix
definitions = {
  dev-server = 3000;
  nextjs = 3001;
  vite = 5173;
};
```

### `m3ta.ports.hostOverrides`

Host-specific port overrides.

- Type: `attrsOf (attrsOf int)`
- Default: `{}`

Example:

```nix
hostOverrides = {
  laptop = {
    vite = 5174;
  };
  desktop = {
    vite = 5173;
  };
};
```

### `m3ta.ports.currentHost`

Current hostname.

- Type: `string`
- Example: `"desktop"`

### `m3ta.ports.generateEnvVars`

Generate environment variables from ports.

- Type: `boolean`
- Default: `false`
- Home Manager only

When enabled, generates environment variables like:

```bash
PORT_DEV_SERVER=3000
PORT_NEXTJS=3001
PORT_VITE=5173
```

## Functions

### `config.m3ta.ports.get "service"`

Get port for a service with host-specific override.

```nix
home.sessionVariables = {
  DEV_PORT = toString (config.m3ta.ports.get "dev-server");
};
```

### `config.m3ta.ports.getHostPorts "hostname"`

Get all ports for a specific host.

```nix
laptopPorts = config.m3ta.ports.getHostPorts "laptop";
# Returns: { dev-server = 3000; vite = 5174; ... }
```

### `config.m3ta.ports.listServices`

List all defined service names.

```nix
allServices = config.m3ta.ports.listServices;
# Returns: ["dev-server" "nextjs" "vite"]
```

## Environment Variables

When `generateEnvVars = true`, the following environment variables are generated:

```
PORT_<SERVICE_UPPERCASE>=<port_number>
```

Example:

```nix
m3ta.ports = {
  enable = true;
  definitions = {
    dev-server = 3000;
    nextjs = 3001;
  };
  generateEnvVars = true;
};
```

Generates:

```bash
PORT_DEV_SERVER=3000
PORT_NEXTJS=3001
```

You can then use these in scripts:

```bash
#!/usr/bin/env bash
# Use environment variable directly
npm start --port=$PORT_DEV_SERVER
```

## Usage Examples

### Basic Usage

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
    };
    currentHost = "desktop";
  };

  home.sessionVariables = {
    DEV_PORT = toString (config.m3ta.ports.get "dev-server");
  };
}
```

### With Environment Variables

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };
    currentHost = "desktop";
    generateEnvVars = true;
  };

  # Now available as environment variables
  # PORT_DEV_SERVER=3000
  # PORT_NEXTJS=3001
  # PORT_VITE=5173
}
```

### With Multi-Host Setup

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      vite = 5173;
    };
    hostOverrides = {
      laptop = {
        vite = 5174;
      };
      desktop = {
        vite = 5173;
      };
    };
    currentHost = config.networking.hostName;
    generateEnvVars = true;
  };
}
```

### With Shell Scripts

Create `~/.config/zellij/scripts/dev.ksh`:

```ksh
#!/usr/bin/env ksh
# Start dev server using environment variable
cd ~/projects/my-app
npm start --port=$PORT_DEV_SERVER
```

## Difference from NixOS Module

The Home Manager version has one additional feature:

### `generateEnvVars`

Not available in NixOS module. Generates environment variables for all defined ports:

```nix
# Home Manager
m3ta.ports.generateEnvVars = true;  # Available

# NixOS
# Not available
```

## Related

- [Port Management Guide](../../guides/port-management.md) - Detailed guide
- [NixOS Ports Module](../nixos/ports.md) - System-level port management