Overview

The Serverless module adds adapters so you can run the same Vercube app on AWS Lambda or Azure Functions. Platform-specific HTTP events are converted to the standard Web Request / Response APIs your controllers already use.

Vercel does not use this package: deploy with a fetch handler instead - see Deploy to Vercel.

Installation

$ pnpm add @vercube/serverless

$ npm install @vercube/serverless

$ bun install @vercube/serverless

Entry points

Deploying to each cloud is covered step by step in Deployment:

• AWS Lambda
• Azure Functions

Minimal handler shape

You build a Vercube App once, then wrap it with toServerlessHandler:

import { createApp } from '@vercube/core';
import { toServerlessHandler } from '@vercube/serverless/aws-lambda';

const app = createApp();
export const handler = toServerlessHandler(app);

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,
});

What is serverless hosting?

Providers run your code on demand: no servers to manage, billing roughly tied to execution time, and automatic scaling. This module translates each platform’s event shape into a Request, runs your app, then maps the Response back.

How it works

The adapter sits between the platform and Vercube:

1. Platform event - Lambda or Azure receives HTTP
2. Adapter - builds a standard Request
3. Vercube - controllers and middleware run as usual
4. Adapter - turns the Response into the platform format
5. Platform - returns it to the client

What gets converted

Request: method, path, query, headers (including cookies), body (JSON, forms, binary).

Response: status, headers, Set-Cookie, body (text, JSON, binary).

Performance notes

Initialize once at module scope (app, pools, clients). Creating a new createApp() per invocation wastes cold-start budget. Platform-specific tuning (memory, timeout, concurrency, pooling) is described in the deployment guides:

• AWS Lambda - provisioned concurrency, RDS Proxy, package size
• Azure Functions - Premium plan, Always On, host.json limits

Accessing configuration

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

@Controller('/config')
export class ConfigController {
  @Get('/info')
  getInfo() {
    return {
      environment: process.env.NODE_ENV,
      database: process.env.DATABASE_URL ? 'configured' : 'not configured',
    };
  }
}

Set secrets in each provider’s dashboard or IaC (Serverless Framework, Bicep, Terraform, etc.) - examples live in the AWS and Azure deployment pages.