Migration

Preflight — confirm before committing

Walk these before rewriting anything. A “no” means Web Functions is the wrong destination — see the decision gates in SKILL.md (opens in a new tab).

• Not done: The app is Node.js, or can run on nodejs24.x. Runtime support can change, so confirm the supported runtimes with aws lambda-web help or the AWS docs rather than assuming this is the only one.
• Not done: Every native dependency has an arm64 build, and the deployment package is built on arm64. Execution environments are Graviton, so an x86-built native addon will not load.
• Not done: The entry point can become index.js at the root of the ZIP.
• Not done: No request needs longer than the 900 s (15 min) per-request timeout.
• Not done: The app is safe to run with several concurrent requests in one process — no module-level per-request state. This is the single most common source of post-migration bugs, because Event Functions gave every request its own environment and hid the problem.
• Not done: Nothing depends on state surviving in the environment or /tmp between requests.
• Not done: The package, including node_modules, fits in 512 MB.
• Not done: Every @aws-sdk/* client the code imports is packaged, and none is marked external in the bundler config. Event Functions include the SDK in the runtime; Web Functions do not.
• Not done: 2 vCPU / 2 GB per environment is enough (see Service Limits in SKILL.md (opens in a new tab)).
• Not done: If the current function is VPC-attached, plan an egress network connector for the new revision; subnets and security groups move to the connector (see networking.md (opens in a new tab), and confirm the connector commands with aws lambda-core help or the AWS docs).

Path 1 — Express/Fastify behind an adapter

The common shape: an Express or Fastify app wrapped by serverless-express, @vendia/serverless-express, aws-lambda-fastify, or a hand-rolled event translator.

The router does not change. The wrapper does.

Before:

After:

Steps:

1. Remove the adapter from package.json and delete the handler module.
2. Rename or shim the entry point to index.js, and add "type": "module" if you use import.
3. Add the app.listen(...) call above. Do not hardcode a port.
4. Audit for concurrency safety — see the preflight checklist. Search for module-level let/var that a request writes to.
5. Run it locally with node index.js and curl it. Local and deployed behaviour are now the same code path, which they were not under the adapter.
6. Package and deploy per deployment.md (opens in a new tab).

What you can delete along the way: base64 request/response encoding, isBase64Encoded handling, API Gateway event shape translation, and any context.callbackWaitsForEmptyEventLoop workaround — background work now continues naturally after the response.

Path 2 — API Gateway + Lambda proxy

Two options, and the choice is about which API Gateway features you actually use.

Option A — replace the API with the endpoint. Simplest, and the reason to migrate. The endpoint gives you a managed HTTPS domain directly. Move into the app: CORS (a middleware such as cors), request validation, and authorization (validate the JWT or session in the app).

Choose authType deliberately rather than taking a default. Use IamAuth for service-to-service traffic, so only SigV4-signed callers reach the endpoint. Reach for ApplicationManaged only when the endpoint genuinely must be public, and treat that as a commitment rather than a convenience, because nothing authenticates in front of the app. Its own authentication must be implemented and verified against the new endpoint before any traffic shifts to it. A public endpoint also needs defence in depth beyond authentication: front it with AWS WAF and set the standard security response headers (HSTS, CSP, X-Frame-Options), which helmet handles for Express and Fastify. See iam-and-security.md (opens in a new tab).

Option B — keep API Gateway in front of the endpoint. Keep this when you depend on usage plans and API keys, Cognito or Lambda authorizers, request/response mapping, mTLS, edge WAF, or WebSocket APIs. Treat the endpoint domain as the HTTP integration target.

Either way, translate the handler as in Path 1 — the event-shape code goes away.

Path 3 — Lambda function URL

The closest existing shape — a function already reachable over HTTPS without API Gateway.

1. Drop the handler export; add a listening server as in Path 1.
2. authType here has exactly two values, ApplicationManaged and IamAuth (see iam-and-security.md (opens in a new tab)). A function URL’s NONE corresponds to the first and AWS_IAM to the second; confirm that mapping against the API reference before relying on it for an access-control decision.
3. Response streaming via awslambda.streamifyResponse becomes ordinary Node streaming — write to the response as you go. See architecture-patterns.md (opens in a new tab).
4. There is no reserved- or provisioned-concurrency setting. Bound scale with throttleConfig.rateLimit (RPS) or scalingConfig.maxEnvironments (see scaling-and-concurrency.md (opens in a new tab)); throttleConfig.rateLimit: 0 is the equivalent of the reservedConcurrency: 0 kill switch.
5. The domain changes, so update clients and any DNS records that pointed at the function URL.

Path 4 — Container on Fargate, App Runner or EC2

The app is probably already a listening HTTP server, so the code is close. The packaging is not.

1. There is no OCI image path — the artifact is a ZIP in S3. Reproduce the image’s install step with npm ci --omit=dev and zip the result.
2. Anything the Dockerfile installed outside npm (system packages, native binaries, headless browsers, ImageMagick) has no equivalent. If the app needs it, this is not a Web Functions workload — check aws-lambda-microvms, or ECS/EKS.
3. Long-lived in-process state (a warm cache, a loaded model, in-memory sessions) does not survive; move it to a shared store.
4. Replace the container health check with the readiness contract: bind the host and port from AWS_LAMBDA_HTTP_ENDPOINT within the 10 s init timeout.
5. Sidecars, cron inside the container, and background daemons have no equivalent. Move scheduled work to EventBridge Scheduler plus an Event Function.

Features with no direct equivalent

Plan replacements for these before you migrate, not after:

Feature availability changes, so confirm the layers and container-image rows against aws lambda-web create-web-function-revision help or the API reference before ruling either out.

A mixed application is normal and expected: HTTP surface on a Web Function, queue and stream consumers on Event Functions, in the same account and stack.

Observability deltas when migrating from Event Functions

A new app is fine with the defaults. A migrated app is not: three things move, and each one fails silently rather than erroring.

The log group path changes. Logs go to /aws/lambda/web/{function-name}, plus a {logGroup}.local group holding only the logs of the region that served the request. The Event Functions path /aws/lambda/{function-name} is not created, so aws logs filter-log-events --log-group-name /aws/lambda/{name} returns ResourceNotFoundException. Anything scoped to the old path silently collects nothing:

• Not done: Log shipper subscription filters repointed at /aws/lambda/web/.
• Not done: IAM policies whose Resource is scoped to /aws/lambda/* widened or repointed — a policy written for the old prefix does not match the new group.
• Not done: CloudWatch dashboards and metric filters repointed.
• Not done: Alarms that watched the old group repointed, since an alarm on a log group that never receives data does not fire.

Three Event Functions environment variables are absent. AWS_LAMBDA_LOG_STREAM_NAME, AWS_LAMBDA_LOG_GROUP_NAME and AWS_LAMBDA_FUNCTION_NAME are all unset. Migrated structured logging or tracing code that reads any of them logs an empty value instead of failing, which is worse than an error because it looks like it works. Read AWS_LAMBDA_HTTP_ENDPOINT for the bind address; for correlation use the requestId the platform already injects into every log line, or the lambda-web-request-id and lambda-web-logstream response headers.

The CLI namespace splits. aws lambda list-functions returns only Event Functions and will not show your Web Functions — they are under aws lambda-web list-web-functions. Scripts, runbooks and inventory tooling that enumerate functions with the lambda namespace silently under-report after a migration.

Cutting traffic over

Do not repoint DNS as the first step.

1. Deploy the Web Function alongside the existing stack and curl its endpoint directly.
2. Compare responses against the old endpoint for the routes that matter — status codes, headers, and content type, not just the body.
3. Load-test at expected concurrency so the multi-concurrency behaviour surfaces before customers find it. Watch for cross-request state bleed, not just latency.
4. Shift traffic at the DNS or CDN layer, keeping the old stack warm and ready to take traffic back.
5. Keep the old stack until error rates and p99 latency have been stable across a full traffic cycle, then decommission.

For canarying between revisions of the Web Function itself — as opposed to between old and new stacks — use revisionWeights on the endpoint. See deployment.md (opens in a new tab).

Post-migration verification

• Not done: Endpoint state is Active and curl https://{domainName}/ returns the expected response.
• Not done: A concurrency test at realistic load shows no cross-request data bleed.
• Not done: Logs arrive in the configured log group → observability.md (opens in a new tab).
• Not done: The log group is encrypted with a KMS key. HTTP request and response logs routinely carry tokens, headers and PII, so encrypt by default rather than treating it as a judgement call.
• Not done: authType matches intent — ApplicationManaged endpoints are public.
• Not done: The execution role carries only the permissions the app actually uses.
• Not done: No secrets moved into environmentVariables during the port. Keep them in AWS Secrets Manager or SSM Parameter Store (SecureString) and fetch them at runtime.
• Not done: Every route validates and sanitises its input in the app — a schema library such as Zod, Joi or ajv in middleware. If the source sat behind API Gateway, its request validation on bodies, query parameters and headers is gone, and losing it is silent.
• Not done: ApplicationManaged endpoints sit behind CloudFront and AWS WAF for L7 protection — rate limiting, bot control, IP reputation. The managed domain has no WAF of its own.
• Not done: A CloudWatch alarm on endpoint error rate exists before the traffic shift.