Serverless

Run a NextRush app as a serverless function. The adapter separates the execution model (per-invocation, stateless, timeout→504, warm-instance reuse) from each provider's event format — you import one Tier-1 handler and never touch the mapper plumbing underneath.

Installation

$ pnpm add @nextrush/adapter-serverless

Quick start

import { createApp } from '@nextrush/core';
import { createLambdaHandler } from '@nextrush/adapter-serverless';

const app = createApp();

app.use(async (ctx) => {
  ctx.json({ message: 'Hello from Lambda!' });
});

export const handler = createLambdaHandler(app);

Tier-1 handlers (what you actually import)

// Google Cloud Functions
import { createGoogleHandler } from '@nextrush/adapter-serverless';
import * as functions from '@google-cloud/functions-framework';

functions.http('api', createGoogleHandler(app));

// Azure Functions (v4 model)
import { createAzureHandler } from '@nextrush/adapter-serverless';
import { app as functions } from '@azure/functions';

functions.http('api', { handler: createAzureHandler(app) });

See Google Cloud Functions deployment and Azure Functions deployment for the full deploy commands and platform-specific configuration these two drop-ins need.

Knowing which platform you are on

ctx.runtime is 'edge' on every provider here — this adapter runs on @nextrush/adapter-edge's fetch engine, whose runtime detector has no AWS/GCP/Azure branch. A check for ctx.runtime === 'node' typechecks and never matches.

ctx.platform is the field that names the provider: 'lambda', 'gcf', or 'azure'. Each Tier-1 handler sets it explicitly, so it is declared rather than guessed.

import { createLambdaHandler } from '@nextrush/adapter-serverless';

app.use(async (ctx) => {
  ctx.json({ platform: ctx.platform, runtime: ctx.runtime });
});

export const handler = createLambdaHandler(app);

Each Tier-1 handler accepts ServerlessHandlerOptions:

interface ServerlessHandlerOptions {
  /** Per-invocation timeout (ms). Exceeding it produces a 504 result instead of hanging the invocation. */
  timeout?: number;
}

export const handler = createLambdaHandler(app, { timeout: 5000 });

Advanced: building a custom provider (Tier 3)

See Event mapping for how the built-in mappers above translate a platform event into the same Request/Response every adapter uses — the mental model for what you're implementing below.

Application developers should stop at the Tier-1 handlers above. Implement EventMapper only to add a platform NextRush doesn't ship (Oracle, Fly.io, OpenFaaS, an internal platform):

import { createServerlessAdapter } from '@nextrush/adapter-serverless';
import type { EventMapper } from '@nextrush/adapter-serverless';

const myMapper: EventMapper<MyEvent, MyResult> = {
  name: 'my-platform',
  toRequest(event) {
    /* build a Web Request from the platform event */
  },
  fromResponse(response, event) {
    /* map the Response back to the platform's expected result */
  },
};

const adapter = createServerlessAdapter({ mappers: [myMapper] });
export const handler = adapter.createHandler(app);

mappers is an immutable, per-adapter registry — there is no global mutable mapper registry. When more than one mapper is supplied, an explicit provider name wins; each mapper's optional detect() only runs as a fallback when no provider is named.

Troubleshooting

Every mapper guards the one field it cannot translate without and throws a named [nextrush/serverless] error naming the likely cause (a wrong payload format, or an incomplete hand-written bridge on the *EventHandler path) instead of a raw TypeError from framework internals. On GCF, a request whose rawBody is absent while body is already parsed logs a [nextrush/serverless] warning and omits the body rather than stringifying an object into it.

Because this adapter runs on @nextrush/adapter-edge's engine, that package's development-mode diagnostics apply here too: the ctx.waitUntil() no-op warning (serverless invocations supply no execution context), the boot-reuse warning when createApp() is called inside the exported handler, and the timeout-attribution log accompanying every 504. See @nextrush/adapter-edge for the exact messages.

Related

• Platforms overview
• @nextrush/adapter-edge — Cloudflare Workers, Vercel Edge, Netlify Edge
• Deployment guides