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

npm install --save-dev @meticoeus/terminx

Usage

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

npx @meticoeus/terminx watch

Configuration

The terminx.yaml file expects the following structure:

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:

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

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

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

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]