Configuration

Learn how to configure Lighthouse for your development environment.

Configuration File

Create lighthouse.config.ts in your project root:

import { defineLighthouseConfig } from '@serverless-monolith/lighthouse';

export default defineLighthouseConfig({
  // Proxy configuration
  proxy: {
    port: 5454,
    cors: true,
    logRequests: true,
    defaultTimeout: 30000,
  },

  // Path to Bruno collections
  brunoPath: './bruno',

  // Core groups (services)
  coreGroups: [...],

  // Managed processes
  processes: [...],

  // UI options
  ui: {
    defaultLayout: 'split',
  },
});

Configuration Options

Proxy Configuration

Option	Type	Default	Description
port	number	5454	Proxy server port
cors	boolean	true	Enable CORS
logRequests	boolean	true	Log requests
defaultTimeout	number	30000	Request timeout (ms)

Core Groups

Define your backend services:

coreGroups: [
  {
    coreName: 'user-service',
    baseUrl: 'http://localhost:4005',
    routes: [
      {
        name: 'users',
        pathPrefix: '/api/http/user/',
        timeout: 30000,
      },
      {
        name: 'global',
        routeByPath: {
          'v2/users': {
            pathPrefix: '/api/http/users/',
            preserveMatchedPath: true,
          },
          '': {
            pathPrefix: '/api/http/global/',
          },
        },
      },
    ],
  },
]

Process Configuration

Define managed processes:

processes: [
  {
    id: 'api-server',
    name: 'API Server',
    description: 'Main API service',
    command: 'pnpm',
    args: ['dev'],
    cwd: '/path/to/service',
    mode: 'auto',
    autoStart: false,
    env: {
      NODE_ENV: 'development',
    },
    healthCheck: {  // Required
      url: 'http://localhost:4005/health',
      interval: 5000,
      timeout: 3000,
    },
  },
]

Process Options

Option	Type	Required	Description
id	string	✓	Unique identifier
name	string	✓	Display name
description	string		Process description
command	string	✓	Command to run
args	string[]	✓	Command arguments
cwd	string	✓	Working directory
mode	string	✓	managed, external, or auto
healthCheck	object	✓	Health check config (required)
autoStart	boolean		Start on launch
env	object		Environment variables

Process Modes

Mode	Description
managed	Lighthouse starts and manages the process
external	Process runs outside Lighthouse (just monitors)
auto	Auto-detect: managed if not running, external if already running

Health Check Configuration

The healthCheck field is required for all processes:

healthCheck: {
  url: 'http://localhost:4005/health',  // Required
  interval: 5000,     // Required - Check every 5 seconds (ms)
  timeout: 3000,      // Optional - Timeout after 3 seconds (default: 5000)
}

Option	Type	Required	Default	Description
url	string	✓	-	URL to check health
interval	number	✓	-	Check interval in ms
timeout	number		5000	Timeout per check in ms

UI Options

ui: {
  defaultLayout: 'split',  // 'split' or 'fullscreen'
}

Route Configuration

Simple Route

{
  name: 'users',
  pathPrefix: '/api/http/user/',
  timeout: 30000,
}

Route By Path

For complex routing:

{
  name: 'global',
  routeByPath: {
    'v2/users': {
      pathPrefix: '/api/http/users/',
      preserveMatchedPath: true,
    },
    'admin': {
      pathPrefix: '/api/http/admin/',
      fallbackUrls: ['http://localhost:4006/api/http/admin/'],
    },
    '': {
      pathPrefix: '/api/http/global/',
    },
  },
  timeout: 30000,
}

Route Target Options

Option	Type	Description
pathPrefix	string	Path prefix for backend
preserveMatchedPath	boolean	Keep matched path in request
fallbackUrls	string[]	Fallback URLs on 404
transformPath	function	Transform path before forwarding

Environment Variables

Override configuration with environment variables:

LIGHTHOUSE_PORT=5454
LIGHTHOUSE_CORS=true
LIGHTHOUSE_LOG_REQUESTS=true

Multiple Environments

const isDev = process.env.NODE_ENV !== 'production';

export default defineLighthouseConfig({
  proxy: {
    port: 5454,
    logRequests: isDev,
  },
  brunoPath: './bruno',
  coreGroups: [...],
  processes: isDev ? devProcesses : [],
});

Complete Example

import { defineLighthouseConfig } from '@serverless-monolith/lighthouse';

export default defineLighthouseConfig({
  proxy: {
    port: 5454,
    cors: true,
    logRequests: true,
  },
  brunoPath: './bruno',
  coreGroups: [
    {
      coreName: 'api-service',
      baseUrl: 'http://localhost:4005',
      routes: [
        { name: 'users', pathPrefix: '/api/http/user/' },
        { name: 'orders', pathPrefix: '/api/http/order/' },
      ],
    },
  ],
  processes: [
    {
      id: 'api',
      name: 'API Server',
      command: 'pnpm',
      args: ['dev'],
      cwd: './api',
      mode: 'auto',
      healthCheck: {
        url: 'http://localhost:4005/health',
        interval: 5000,
      },
    },
  ],
  ui: {
    defaultLayout: 'split',
  },
});

Next Steps

• Dashboards - Dashboard features
• Process Management - Managing services