npm package: @meticoeus/terminx
Description: Tmux like terminal UI for NX multi-server monorepos using traefik.
Author: meticoeus
Latest version: 0.3.0

# Terminx

A tmux-like terminal UI for managing multiple services in NX monorepos, inspired by the developer UI in SST v3.

## Overview

Terminx provides a simple, powerful interface for running and monitoring multiple services in your NX monorepo project.
It streamlines the development workflow by providing a single terminal interface to manage all your services using traefik for unified routing.

## Installation

```shell script
npm install --save-dev @meticoeus/terminx
```

## Usage

To use Terminx, create a `terminx.yaml` configuration file in your repository root, then run:

```shell script
npx @meticoeus/terminx watch
```

## Configuration

The `terminx.yaml` file expects the following structure:

```yaml
commands: # optional, uses defaults below
  build: 'nx run-many --target=build --all' # Optional, defaults shown
  watch: 'nx run-many --target=watch --all --parallel' # Optional, defaults shown

services:
  # Define each service in your NX monorepo
  service-a:
    environment: # Environment variables for this service
      PG_CONNECTION: 'postgresql://user:password@localhost:5432/db_a'

  service-b:
    environment:
      PG_CONNECTION: 'postgresql://user:password@localhost:5432/db_b'

traefik:
  dir: 'traefik' # Required: Directory containing local development Traefik configuration
  source: 'src' # Optional: Source directory for Traefik configs (default shown)
  target: 'dynamic' # Optional: Target directory for generated configs (default shown)
```

### Configuration Options

#### Commands

Customize commands for building and watching your NX projects:

- `build`: Command to build services
- `watch`: Command to watch services for changes

If you want to configure a subset of services, you could specify a [list of tasks to run](https://nx.dev/features/run-tasks#run-tasks-on-projects-affected-by-a-pr):

```yaml
commands:
  build: 'nx run-many --target=build -p service-a service-b'
  watch: 'nx run-many --target=watch -p service-a service-b --parallel'
```

Or you could use [tags](https://nx.dev/features/enforce-module-boundaries#tags)

service-a project.json
service-b project.json

```json
{
  "tags": ["scope:services"]
}
```

```yaml
commands:
  build: 'nx run-many --target=build --projects=tag:scope:services'
  watch: 'nx run-many --target=watch --projects=tag:scope:services --parallel'
```

#### Services

Each service you want to run in your NX monorepo must be defined here.
The service name must match the project name in your NX workspace or project.json file.

- `environment`: Environment variables to pass to the service

#### Traefik

Configuration for Traefik integration:

- `dir`: Path to the Traefik configuration directory (required)
  - The directory must contain a docker-compose.yaml file to use to launch traefik
- `source`: Source directory for Traefik configurations (default: "src")
- `target`: Target directory for generated Traefik configurations (default: "dynamic")

In your source config files, document the port of each service using $<NAME_IN_SNAKE_CASE>\_PORT, e.g. $SERVICE_A_PORT.
These will be replaced in the dynamic version with your services' current ports.
Ports are chosen from your operating system's ephemeral port pool dynamically so only your primary port that traefik listens to needs to be free.

## Project Structure Requirements

Terminx expects:

1. An NX monorepo with a valid `nx.json` file in the repository root
2. Each service defined in the `services` section of `terminx.yaml` must have a corresponding directory in your NX workspace's app directory (by default `servers/`)
3. Each service directory must contain a valid `project.json` file

## Example

Check out the `example/` directory for a complete example project showing how to set up and use Terminx with a multi-service NX monorepo.

## Key Features

- **Unified Terminal UI**: View the logs of all your services in a single terminal
- **Process Management**: Start and monitor all your services
- **Traefik Integration**: Automatically generate Traefik configurations for your services

## License

[License information]