Terminal Composer (tcomposer)

A CLI tool to orchestrate and launch multiple services/applications simultaneously. Perfect for developers working with microservices or monorepos who need to start multiple services for local development.

Features

• Parallel Execution: Start multiple services in parallel with colored output prefixes
• Dependency Management: Define service dependencies to ensure correct startup order
• Ready Detection: Detect when a service is ready based on stdout output patterns
• Interactive Mode: Checkbox-style service selection with -i flag
• Native Terminals: Open each service in a separate terminal window with --detach
• YAML Configuration: Simple and readable configuration format

Installation

# Run directly with npx
npx tcomposer up

# Or install globally
npm install -g tcomposer

Quick Start

1. Create a configuration file in your project root:

npx tcomposer init

2. Edit composer.yml to define your services:

version: "1"

services:
  database:
    name: "PostgreSQL"
    path: "./docker"
    command: "docker-compose up postgres"
    
  backend:
    name: "API Server"
    path: "./backend"
    command: "npm run dev"
    depends_on:
      - database
    ready_when: "Server listening on port"
    
  frontend:
    name: "React App"
    path: "./frontend"
    command: "npm start"
    depends_on:
      - backend
    env:
      REACT_APP_API_URL: "http://localhost:3001"

3. Start your services:

npx tcomposer up

Commands

tcomposer up [services...]

Start services defined in composer.yml.

# Start all services
tcomposer up

# Start specific services (dependencies included automatically)
tcomposer up frontend backend

# Interactive mode - select services with checkboxes
tcomposer up -i
tcomposer up --interactive

# Open each service in a separate terminal window
tcomposer up --detach
tcomposer up -d

# Use a custom config file
tcomposer up -c ./custom-config.yml

tcomposer init

Create a sample composer.yml configuration file.

tcomposer init

# Overwrite existing config
tcomposer init --force

tcomposer list

List all configured services.

tcomposer list
tcomposer ls

tcomposer validate

Validate the configuration file.

tcomposer validate

Configuration Reference

Service Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | name | string | No | Display name for the service (defaults to service key) | | path | string | Yes | Working directory for the command | | command | string | Yes | Command to execute | | depends_on | string[] | No | List of service IDs that must start first | | ready_when | string | No | Text pattern to detect in stdout when service is ready | | env | object | No | Environment variables for the service |

Example Configuration

version: "1"

services:
  redis:
    name: "Redis"
    path: "."
    command: "redis-server"
    ready_when: "Ready to accept connections"

  api:
    name: "API Server"
    path: "./api"
    command: "npm run dev"
    depends_on:
      - redis
    ready_when: "Listening on port 3000"
    env:
      REDIS_URL: "redis://localhost:6379"
      NODE_ENV: "development"

  worker:
    name: "Background Worker"
    path: "./worker"
    command: "npm run worker"
    depends_on:
      - redis
      - api

  web:
    name: "Web Frontend"
    path: "./web"
    command: "npm start"
    depends_on:
      - api
    env:
      REACT_APP_API_URL: "http://localhost:3000"

Output Example

🚀 Terminal Composer
Starting 4 service(s): Redis, API Server, Background Worker, Web Frontend

[Redis     ] Starting: redis-server
[Redis     ] Ready to accept connections
[Redis     ] ✓ Service is ready
[API Server] Starting: npm run dev
[API Server] Listening on port 3000
[API Server] ✓ Service is ready
[Worker    ] Starting: npm run worker
[Worker    ] Connected to Redis
[Web       ] Starting: npm start
[Web       ] Compiled successfully!

Press Ctrl+C to stop all services

Supported Platforms

Native Terminal Mode (--detach)

| Platform | Supported Terminals | |----------|---------------------| | macOS | iTerm2, Terminal.app | | Linux | gnome-terminal, konsole, xterm | | Windows | Windows Terminal, cmd.exe |

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Run locally
node bin/tcomposer.js --help

Author

Created by Jmzp

License

MIT License - see the LICENSE file for details.