Basic Usage

A complete example of setting up and using the Proxy package.

Scenario

You have three serverless services running locally:

• User Service on port 4005
• Order Service on port 4006
• Product Service on port 4007

You want to access all of them through a single endpoint on port 5454.

Setup

Install the Package

pnpm add @serverless-monolith/proxy

Create Proxy Configuration (Recommended)

Using coreGroups for better organization:

// proxy.ts
import { ProxyServer } from '@serverless-monolith/proxy';

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  logRequests: true,
  defaultTimeout: 30000,
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        {
          name: 'user-service',
          pathPrefix: '/api/http/user/',
        },
      ],
    },
    {
      coreName: 'serverless-orders',
      baseUrl: 'http://localhost:4006',
      routes: [
        {
          name: 'order-service',
          pathPrefix: '/api/http/order/',
        },
      ],
    },
    {
      coreName: 'serverless-products',
      baseUrl: 'http://localhost:4007',
      routes: [
        {
          name: 'product-service',
          pathPrefix: '/api/http/product/',
        },
      ],
    },
  ],
});

async function main() {
  await proxy.start();
  console.log('Proxy running on http://localhost:5454');
  console.log('Routes:');
  console.log('  /user-service/*    → http://localhost:4005/api/http/user/');
  console.log('  /order-service/*   → http://localhost:4006/api/http/order/');
  console.log('  /product-service/* → http://localhost:4007/api/http/product/');
}

main().catch(console.error);

Legacy Configuration (cores)

Using cores (still supported but deprecated):

// proxy.ts
import { ProxyServer } from '@serverless-monolith/proxy';

const proxy = new ProxyServer({
  port: 5454,
  cors: true,
  logRequests: true,
  defaultTimeout: 30000,
  cores: [
    {
      name: 'user-service',
      url: 'http://localhost:4005/api/http/user/',
      pathPrefix: '/users',
    },
    {
      name: 'order-service',
      url: 'http://localhost:4006/api/http/order/',
      pathPrefix: '/orders',
    },
    {
      name: 'product-service',
      url: 'http://localhost:4007/api/http/product/',
      pathPrefix: '/products',
    },
  ],
});

Start the Proxy

npx tsx proxy.ts

Testing

# User service
curl http://localhost:5454/user-service
curl http://localhost:5454/user-service/123

# Order service
curl http://localhost:5454/order-service
curl -X POST http://localhost:5454/order-service \
  -H "Content-Type: application/json" \
  -d '{"userId": "123", "products": ["p1", "p2"]}'

# Product service
curl http://localhost:5454/product-service
curl http://localhost:5454/product-service/abc

Advanced Example

With Fallback and Route By Path

import { ProxyServer } from '@serverless-monolith/proxy';

const proxy = new ProxyServer({
  port: 5454,
  cors: {
    origin: ['http://localhost:3000'],
    credentials: true,
  },
  logRequests: true,
  coreGroups: [
    {
      coreName: 'serverless-sst',
      baseUrl: 'http://localhost:4005',
      routes: [
        // Simple routing
        {
          name: 'user-service',
          pathPrefix: '/api/http/user/',
          timeout: 10000,
        },
        
        // Complex routing with routeByPath
        {
          name: 'api',
          routeByPath: {
            'v2/users': {
              pathPrefix: '/api/http/users/',
              preserveMatchedPath: true,
            },
            'v2/orders': {
              pathPrefix: '/api/http/orders/',
              preserveMatchedPath: true,
            },
            'v1': {
              pathPrefix: '/api/http/legacy/',
              transformPath: (path) => path.replace('/v1/', '/'),
            },
            '': {
              pathPrefix: '/api/http/global/',
            },
          },
        },
      ],
    },
    
    // Service with fallback for migration
    {
      coreName: 'serverless-orders',
      baseUrl: 'http://localhost:4006',
      routes: [
        {
          name: 'order-service',
          pathPrefix: '/api/http/order/',
          routeByPath: {
            '': {
              pathPrefix: '/api/http/order/',
              fallbackUrls: [
                'http://localhost:4005/api/http/order/',
              ],
            },
          },
        },
      ],
    },
  ],
});

Integration with Lighthouse

Use with Lighthouse TUI for a complete development experience:

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

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

Package.json Scripts

{
  "scripts": {
    "proxy": "tsx proxy.ts",
    "dev": "concurrently \"pnpm proxy\" \"pnpm --filter user-service dev\" \"pnpm --filter order-service dev\"",
    "lighthouse": "lighthouse"
  }
}