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.