Overview

The Serverless module enables you to deploy your Vercube applications to serverless platforms with zero configuration. Instead of managing servers and infrastructure, you wrap your Vercube app with a simple adapter and deploy it to AWS Lambda, Azure Functions, or other serverless providers - your existing controllers, middleware, and business logic work exactly as before.

Installation

$ pnpm add @vercube/serverless

$ npm install @vercube/serverless

$ bun install @vercube/serverless

Quick Start

import { createApp } from '@vercube/core';
import { Controller, Get } from '@vercube/core';

@Controller('/api')
export class ApiController {
  
  @Get('/hello')
  getHello() {
    return { message: 'Hello from Serverless!' };
  }
  
  @Get('/users/:id')
  getUser(@Param('id') id: string) {
    return { id, name: 'John Doe' };
  }
}

export const app = createApp();

// lambda.ts
import { toServerlessHandler } from '@vercube/serverless/aws-lambda';
import { app } from './src/index';

export const handler = toServerlessHandler(app);

// src/functions/httpTrigger.ts
import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
import { toServerlessHandler } from '@vercube/serverless/azure-functions';
import { app as vercubeApp } from '../index';

const handler = toServerlessHandler(vercubeApp);

export async function httpTrigger(
  request: HttpRequest, 
  context: InvocationContext
): Promise<HttpResponseInit> {
  return await handler(request);
}

app.http('httpTrigger', {
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
  authLevel: 'anonymous',
  handler: httpTrigger,
});

# serverless.yml
service: vercube-api

provider:
  name: aws
  runtime: nodejs22.x
  region: us-east-1

functions:
  api:
    handler: lambda.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY
          cors: true

// host.json
{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 20
      }
    }
  }
}

What is Serverless Deployment?

Serverless platforms like AWS Lambda and Azure Functions run your code on-demand without requiring you to manage servers. You pay only for actual execution time, and the platform automatically scales based on traffic. The serverless module bridges the gap between these platform-specific event formats and your standard Vercube application.

How It Works

The serverless adapter acts as a translation layer between platform-specific events and standard web requests:

1. Platform Event - Lambda or Azure Functions receives an HTTP event
2. Adapter Converts - The serverless handler converts it to a standard Request object
3. Vercube Processes - Your app handles it using normal controllers and middleware
4. Response Converted - The adapter converts your Response back to platform format
5. Platform Returns - The serverless function returns the properly formatted response

What Gets Converted

Request Conversion:

• HTTP method (GET, POST, etc.)
• URL path and query parameters
• Headers (including cookies)
• Request body (JSON, form data, binary)

Response Conversion:

• Status code
• Response headers
• Cookies (Set-Cookie headers)
• Response body (text, JSON, binary)

Performance Considerations

Container Reuse

Serverless platforms reuse containers across invocations:

// ✅ Good - Module-level initialization (happens once)
const app = createApp();
const redisClient = createRedisClient();

export const handler = toServerlessHandler(app);

// ❌ Bad - Reinitializes on every request
export const handler = async (event) => {
  const app = createApp(); // Wasteful!
  return toServerlessHandler(app)(event);
};

Memory Management

Configure memory based on your application needs:

# AWS Lambda
functions:
  api:
    handler: lambda.handler
    memorySize: 512  # MB - adjust based on your app
    timeout: 30      # seconds

Concurrent Requests

Serverless platforms handle concurrency differently:

AWS Lambda:

• Each function instance handles one request at a time
• Platform creates new instances for concurrent requests
• Maximum concurrent executions: 1000 (default, configurable)

Azure Functions:

• Each function instance can handle multiple requests
• More cost-effective for high-traffic scenarios
• Concurrency controlled by maxConcurrentRequests

Environment Configuration

Platform-Specific Environment Variables

# serverless.yml
provider:
  environment:
    NODE_ENV: production
    DATABASE_URL: ${env:DATABASE_URL}
    REDIS_URL: ${env:REDIS_URL}
    JWT_SECRET: ${env:JWT_SECRET}

// local.settings.json (for local development)
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "",
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost:5432/myapp"
  }
}

Accessing Configuration

import { RuntimeConfig } from '@vercube/core';

@Controller('/config')
export class ConfigController {
  
  @Inject(RuntimeConfig)
  private config!: RuntimeConfig;
  
  @Get('/info')
  getInfo() {
    return {
      environment: process.env.NODE_ENV,
      platform: process.env.AWS_REGION ? 'aws' : 'azure',
      database: process.env.DATABASE_URL ? 'connected' : 'disconnected'
    };
  }
}