Serverless Offline Edge Lambda

1.3.1 verified Fri May 01 auth: no javascript

A Serverless Framework plugin (v1.3.1, last updated August 2023) that simulates AWS CloudFront Edge Lambda behavior in local development, enabling testing of viewer-request, viewer-response, origin-request, and origin-response events without deploying to AWS. Unlike serverless-offline (which it cannot be used with), it targets CloudFront edge functions specifically, supporting custom headers, transpilers (serverless-webpack, serverless-plugin-typescript serverless-bundle, esbuild), hot reload via chokidar, and configuration through serverless.yml. Requires serverless >=1.36.0 and ships TypeScript types. Release cadence is sporadic with minor fixes and features.

Common errors

error Error: Cannot find module 'serverless-offline-edge-lambda' ↓

cause Plugin not installed or not in devDependencies.

fix

Run npm install --save-dev serverless-offline-edge-lambda

error Configuration error: 'lambdaAtEdge' is not defined ↓

cause The plugin is not listed in the plugins section of serverless.yml.

fix

Add 'serverless-offline-edge-lambda' to the plugins list.

error Error: Cannot start offline because serverless-offline is also installed ↓

cause Both plugins define the 'offline' command.

fix

Remove serverless-offline from dependencies.

error TypeError: Cannot read property 'startsWith' of undefined ↓

cause The handler path in lambdaAtEdge is incorrectly formatted or missing.

fix

Ensure handler format is like 'src/handlers.onViewerRequest' with function name after the dot.

Warnings

gotcha Cannot use with serverless-offline: both plugins define the 'offline' command, causing conflicts. ↓

fix Use only serverless-offline-edge-lambda for CloudFront edge testing; do not install serverless-offline.

gotcha Hot reload requires path to built handlers; incorrect path causes no hot reload. ↓

fix Specify custom.offlineEdgeLambda.path to point to the output directory of your transpiler (e.g., '.build', '.webpack/service').

deprecated Node.js 12 runtime is used in example; newer runtimes (14, 16, 18) are supported but not shown. ↓

fix Set provider.runtime to nodejs14.x, nodejs16.x, or nodejs18.x as needed.

Install

npm install serverless-offline-edge-lambda

yarn add serverless-offline-edge-lambda

pnpm add serverless-offline-edge-lambda

Imports

plugin
wrong
```
constants:
  - serverless-offline-edge-lambda
```
correct
```
plugins:
  - serverless-offline-edge-lambda
```
Must be listed in the plugins section of serverless.yml, not as a require in code.

custom.offlineEdgeLambda

wrong

custom:
  serverless-offline-edge-lambda:
    path: '.build'

correct

custom:
  offlineEdgeLambda:
    path: '.build'

Configuration goes under custom.offlineEdgeLambda, not a plugin-specific top-level key.

lambdaAtEdge

wrong

functions:
  myFunction:
    handler: src/handler.onViewerRequest
    lambdaAtEdge:
      Distribution: 'MyDistribution'
      eventType: 'viewer-request'

correct

functions:
  myFunction:
    handler: src/handler.onViewerRequest
    lambdaAtEdge:
      distribution: 'MyDistribution'
      eventType: 'viewer-request'

The case for lambdaAtEdge fields must be lowercase (distribution, eventType, pathPattern) matching the convention used by serverless-plugin-cloudfront-lambda-edge.

Quickstart

Shows complete setup of serverless-offline-edge-lambda with a sample function and CloudFront distribution in serverless.yml, plus the command to start offline.

npm install --save-dev serverless serverless-offline-edge-lambda

# serverless.yml
service: edge-lambdas

plugins:
  - serverless-offline-edge-lambda

provider:
  name: aws
  runtime: nodejs12.x

functions:
  lambda:
    handler: src/handlers.onViewerRequest
    lambdaAtEdge:
      distribution: 'WebsiteDistribution'
      eventType: 'viewer-request'
      pathPattern: '/lambda'

resources:
  Resources:
    WebsiteDistribution:
      Type: 'AWS::CloudFront::Distribution'
      Properties:
        DistributionConfig:
          DefaultCacheBehavior:

# Start offline
npx serverless offline start --port=3000