serverless-local-ecr

Use a normal source handler with serverless invoke local while deploying the same Lambda function as an Amazon ECR container image.

Serverless Framework does not natively invoke image-backed Lambda functions locally. This plugin keeps handler in place for local commands, then replaces it with image immediately before Serverless packages or deploys the function.

[!IMPORTANT] This plugin does not pull or run the ECR image locally. It invokes the configured source handler using Serverless Framework's normal local runtime.

Requirements

• Node.js 18.18 or newer
• Serverless Framework 3 or 4
• AWS provider

Installation

npm install --save-dev serverless-local-ecr

Add the plugin to serverless.yml:

plugins:
  - serverless-local-ecr

Configuration

Define the local handler and use remoteImage in place of Serverless's standard function-level image property:

service: example

provider:
  name: aws
  runtime: nodejs20.x
  ecr:
    images:
      myImage:
        path: ./image

plugins:
  - serverless-local-ecr

functions:
  myFunction:
    handler: src/handler.main
    remoteImage:
      name: myImage

remoteImage accepts the same common forms as Serverless's image setting:

functions:
  namedImage:
    handler: src/named.main
    remoteImage: myImage

  ecrUri:
    handler: src/existing.main
    remoteImage:
      uri: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-image:latest
      command:
        - src/existing.main

Now the two workflows use different representations of the same function:

# Runs src/handler.main from the local source tree.
serverless invoke local --function myFunction

# Replaces handler with image before creating deployment artifacts.
serverless package
serverless deploy

# The transformation also applies to individual function deployments.
serverless deploy function --function myFunction

Defining remoteImage without handler, or defining both remoteImage and image, is rejected with a configuration error.

Drawbacks and limitations

Local invocation does not test the artifact that is deployed. A successful local invocation can still result in a broken Lambda image because this plugin does not validate:

• the Dockerfile or image build;
• the container entry point, command, or working directory;
• dependencies and files installed or copied only inside the image;
• Linux-native binaries, filesystem permissions, or the container user;
• differences between ARM64 and x86_64 architectures;
• the Lambda Runtime Interface Client or Runtime Interface Emulator;
• environment variables and filesystem layout supplied by the image.

The source handler and the container entry point can also drift over time. Test the built image separately when container fidelity matters. For example, run it with Docker and the AWS Lambda Runtime Interface Emulator, or use AWS SAM CLI's local invocation support.

The plugin changes Serverless's in-memory function configuration during packaging. Although the integration is covered by tests, Serverless lifecycle or configuration internals can change between major releases. Pin Serverless to a version validated by your project and test upgrades before adopting them.

Finally, serverless invoke local is an emulator even for handler-based functions. It does not reproduce every AWS Lambda service behavior, IAM permission, or event source.

Development

npm install
npm run check

See CONTRIBUTING.md for the release and compatibility workflow.

License

ISC