@ai-universe/typescript-server-launcher

Generic TypeScript server launcher with advanced port management, process control, and build orchestration.

Features

• ✅ Configurable Port Selection: Preferred port with automatic fallback
• ✅ Process Management: PID tracking, graceful/forceful termination, cross-platform support
• ✅ Build Orchestration: Automatic dependency installation, TypeScript compilation, custom prepare scripts
• ✅ Watch Mode: Auto-restart on file changes for development
• ✅ Production Mode: Single-run server startup for production
• ✅ Retry Logic: Automatic retry for EADDRINUSE (port conflict) errors
• ✅ Lifecycle Hooks: Custom callbacks for build stages and server events
• ✅ Port Reclamation: Force reclaim ports by terminating existing processes

Installation

npm install @ai-universe/typescript-server-launcher

Quick Start

import { TypeScriptServerLauncher } from '@ai-universe/typescript-server-launcher';

const launcher = new TypeScriptServerLauncher({
  serverDir: 'backend',
  devCommand: ['npm', 'run', 'dev'],
  startCommand: ['npm', 'run', 'start']
});

await launcher.launch();

Documentation

See docs/TYPESCRIPT_SERVER_LAUNCHER_LIBRARY.md for comprehensive documentation including:

• Complete API reference
• Configuration options
• Usage examples
• Migration guide
• Best practices

API Reference

TypeScriptServerLauncher

Main orchestrator class for launching TypeScript servers.

const launcher = new TypeScriptServerLauncher({
  projectRoot?: string;
  serverDir: string;
  devCommand: string[];
  startCommand: string[];
  preferredPort?: number;
  minPort?: number;
  maxPort?: number;
  forcePort?: boolean;
  watchMode?: boolean;
  env?: Record<string, string>;
  buildCommand?: string[];
  skipDependencyInstall?: boolean;
  skipBuild?: boolean;
  prepareScriptPath?: string;
  maxRetries?: number;
  pidFile?: string;
  onBeforeBuild?: () => Promise<void> | void;
  onAfterBuild?: () => Promise<void> | void;
  onServerStarted?: (port: number, pid: number) => Promise<void> | void;
  onServerExit?: (code: number | null) => Promise<void> | void;
});

await launcher.launch();  // Launch with full build pipeline
await launcher.stop();    // Stop the server
const port = launcher.getPort();  // Get current port
const pid = launcher.getPid();    // Get process PID

Port Management

import { findAvailablePort, isPortAvailable, parsePortEnv } from '@ai-universe/typescript-server-launcher';

// Find available port with randomized search
const port = await findAvailablePort({ minPort: 2000, maxPort: 2500 });

// Check if specific port is available
const available = await isPortAvailable(3000);

// Parse port from environment variable
const port = parsePortEnv(process.env.PORT, 'PORT') ?? 2000;

Process Management

import {
  isProcessAlive,
  terminateProcessByPid,
  writePidFile,
  readPidFile,
  removePidFile
} from '@ai-universe/typescript-server-launcher';

// Check if process is running
if (isProcessAlive(1234)) {
  await terminateProcessByPid(1234);
}

// PID file management
writePidFile('/path/to/pid', 1234);
const pid = readPidFile('/path/to/pid');
removePidFile('/path/to/pid');

Build Orchestration

import {
  checkAndInstallDependencies,
  buildTypeScript,
  runCustomPrepareScript
} from '@ai-universe/typescript-server-launcher';

// Install dependencies if needed
checkAndInstallDependencies('/path/to/project');

// Build TypeScript project
buildTypeScript('/path/to/project');

// Run custom prepare script
runCustomPrepareScript('scripts/prepare.mjs', '/path/to/project');

License

MIT

Author

AI Universe Team