dherault/serverless-offline

Serverless Offline

^{Special thanks to:}

Sunshine

The modern virtual office for remote teams

Boost your team communication and culture

This Serverless plugin emulates AWS λ and API Gateway on your local machine to speed up your development cycles. To do so, it starts an HTTP server that handles the request's lifecycle like APIG does and invokes your handlers.

Features

• Node.js, Python, Ruby, Go, Java (incl. Kotlin, Groovy, Scala) λ runtimes.
• Velocity templates support.
• Lazy loading of your handler files.
• And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, CORS, etc.

This plugin is updated by its users, I just do maintenance and ensure that PRs are relevant to the community. In other words, if you find a bug or want a new feature, please help us by becoming one of the contributors :v: ! See the contributing section.

Documentation

• Installation
• Usage and command line options
• Run modes
• Invoke Lambda
• The process.env.IS_OFFLINE variable
• Docker and Layers
• Authorizers
  • API keys
  • Custom authorizers
  • Remote authorizers
  • JWT authorizers
  • Serverless plugin authorizers
• Custom headers
• Environment variables
• AWS API Gateway Features
  • Velocity Templates
    • Velocity nuances
  • CORS
  • Catch-all Path Variables
  • ANY method
  • Lambda and Lambda Proxy Integrations
  • HTTP Proxy
  • Response parameters
• WebSocket
• Debug process
• Resource permissions and AWS profile
• Simulation quality
• Usage with other plugins
• Credits and inspiration
• License
• Contributing
• Contributors

Installation

First, add Serverless Offline to your project:

npm install serverless-offline --save-dev

Then inside your project's serverless.yml file add the following entry to the plugins section: serverless-offline. If there is no plugin section you will need to add it to the file.

Note that the "plugin" section for serverless-offline must be at root level on serverless.yml.

It should look something like this:

plugins:
  - serverless-offline

You can check whether you have successfully installed the plugin by running the serverless command line:

serverless --verbose

The console should display Offline as one of the plugins now available in your Serverless project.

Usage and command line options

In your project root, run:

serverless offline or sls offline.

To list all the options for the plugin, run:

sls offline --help

All CLI options are optional:

corsAllowHeaders

Used as default Access-Control-Allow-Headers header value for responses. Delimit multiple values with commas.
Default: 'accept,content-type,x-api-key'

corsAllowOrigin

Used as default Access-Control-Allow-Origin header value for responses. Delimit multiple values with commas.
Default: '*'

corsDisallowCredentials

When provided, the Access-Control-Allow-Credentials header isn't sent, instead of 'true'. It applies to the Lambda invoke endpoint, and to the REST API endpoints with CORS enabled when an HTTP API CORS configuration is set, unless their cors.allowCredentials setting says otherwise. Without an HTTP API CORS configuration, the HTTP and ALB servers always send the header.
Default (without flag): credentials are allowed ('true')

corsExposedHeaders

Used as additional Access-Control-Exposed-Headers header value for responses. Delimit multiple values with commas.
Default: 'WWW-Authenticate,Server-Authorization'

disableCookieValidation

Used to disable cookie-validation on hapi.js-server.

dockerHost

The host name of Docker.
Default: localhost

dockerHostServicePath

Defines the service path used by SLS running inside a Docker container.

dockerNetwork

The network that the Docker container will connect to.

dockerReadOnly

Marks if the docker code layer should be read only.
Default: true

enforceSecureCookies

Enforce secure cookies

host

Host name to listen on.
Default: localhost

httpPort

Http port to listen on.
Default: 3000

httpsProtocol

To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files.

ignoreJWTSignature

When using HttpApi with a JWT authorizer, don't check the signature of the JWT token.

lambdaPort

Lambda http port to listen on.
Default: 3002

layersDir

The directory layers should be stored in.
Default: '${codeDir}/.serverless-offline/layers'

localEnvironment

Copy local environment variables.
Default: false

localLayers

A mapping of Lambda layer version ARNs to local ZIP files or extracted directories. This option is available in custom.serverless-offline when using Docker.
Default: {}

noAuth

Turns off all authorizers.

noPrependStageInUrl

Don't prepend http routes with the stage.

noSponsor

Remove sponsor message from the output.

noTimeout

Disables the timeout feature.

prefix

Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead.
Default: ''

reloadHandler

Reloads handler with each request. Without it, Node.js, Python, Ruby and Docker handler instances are reused and keep running the code they loaded, until they are terminated (see Handler lifecycle). Has no effect with useInProcess. To reload only after code changes, see Reloading handlers after code changes.

rubyWatchDirs

List of directories to watch for Ruby file changes. Automatically restarts the Ruby process on change, enabling hot-reload during local development.

resourceRoutes

Turns on loading of your HTTP proxy settings from serverless.yml.

terminateIdleLambdaTime

Number of seconds until an idle function is eligible for termination.
Default: 60

useDocker

Run handlers in a docker container.

useInProcess

Run handlers in the same process as 'serverless-offline'.

webSocketHardTimeout

Set WebSocket hard timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table).
Default: 7200 (2 hours)

webSocketIdleTimeout

Set WebSocket idle timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table).
Default: 600 (10 minutes)

websocketPort

WebSocket port to listen on.
Default: 3001

preLoadModules

Pre-load specified modules in the main thread to avoid crashes when importing in worker threads. Provide module names as a comma-separated list (e.g., "sharp,canvas"). Modules are resolved from serverless-offline itself, not from your service directory, so use package names or absolute paths (e.g. ${env:PWD}/my-module.js).
Default: ''

Any of the CLI options can be added to your serverless.yml. For example:

custom:
  serverless-offline:
    httpsProtocol: "dev-certs"
    httpPort: 4000
    foo: "bar"

Options passed on the command line override YAML options.

By default you can send your requests to http://localhost:3000/. Please note that:

• You'll need to restart the plugin if you modify your serverless.yml or any of the default velocity template files.
• When no Content-Type header is set on a request, API Gateway defaults to application/json, and so does the plugin. But if you send an application/x-www-form-urlencoded or a multipart/form-data body with an application/json (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw data as input), whereas the plugin will answer 400 (malformed JSON). Please consider explicitly setting your requests' Content-Type and using separate templates.

Run modes

node.js

Lambda handlers with serverless-offline for the node.js runtime can run in different execution modes, each with its own pros and cons. They are currently mutually exclusive and it's not possible to use a combination, e.g. use in-process for one Lambda, and worker-threads for another. It is planned to combine the flags into one single flag in the future and also add support for combining run modes.

worker-threads (default)

• handlers run in their own context
• memory is not being shared between handlers, memory consumption is therefore higher
• memory is being released when handlers reload or after usage
• environment (process.env) is not being shared across handlers
• global state is not being shared across handlers
• easy debugging

NOTE:

• native modules need to be a Node-API addon or be declared as context-aware using NODE_MODULE_INIT(): https://nodejs.org/docs/latest/api/addons.html#worker-support

in-process

• handlers run in the same context (instance) as serverless and serverless-offline
• memory is being shared across lambda handlers as well as with serverless and serverless-offline
• no reloading capabilities as it is [currently] not possible to implement for commonjs handlers (without memory leaks) and for esm handlers
• environment (process.env) is being shared across handlers as well as with serverless and serverless-offline
• global state is being shared across lambda handlers as well as with serverless and serverless-offline
• easy debugging

docker

• handlers run in a docker container
• memory is not being shared between handlers, memory consumption is therefore higher
• memory is being released when handlers reload or after usage
• environment (process.env) is not being shared across handlers
• global state is not being shared across handlers
• debugging more complicated

Python, Ruby, Go, Java (incl. Kotlin, Groovy, Scala)

The Lambda handler process is running in a child process.

Go

Without Docker, go1.x functions are built from source on each invocation, so Go needs to be installed and handler must point to the Go source file of the function, e.g. hello/main.go.

A handler that points to a compiled binary, e.g. bin/hello as used for deployments, only works with --useDocker. The same applies to the provided.al2023 and provided.al2 runtimes, which AWS recommends for Go since go1.x is deprecated: run them with --useDocker, with the bootstrap binary in your service directory or in a layer.

Handler lifecycle

Node.js, Python and Ruby handlers, as well as all handlers run with --useDocker, run in an instance of the function (a worker thread, a child process or a Docker container, depending on the run mode):

• an idle instance is reused for the next invocation of the same function, concurrent invocations each get a new instance. Unlike on AWS, there is no concurrency limit.
• with reloadHandler, every invocation gets a new instance.
• instances which are idle for terminateIdleLambdaTime seconds are terminated. The check runs every terminateIdleLambdaTime seconds, so an idle instance usually lives one to two times that long, and longer while a previous cleanup (e.g. of a Docker container) is still in progress. Worker threads are terminated abruptly, without notifying your code. Ruby processes receive a SIGTERM, and Docker containers are stopped with docker stop, so they can react to it. Python processes are sent a SIGTERM as well, but since they are started through a shell, the signal may only reach the shell and not the Python interpreter. Either way, pending work such as timers and open connections is not guaranteed to finish.
• in in-process mode, handler modules are loaded once and stay loaded until serverless-offline exits. All invocations share the same module state, and two invocations of the same function can run at the same time against that state, which never happens on AWS.

Without Docker, Go handlers are built and started in a new process for each invocation, so nothing is kept between invocations. Java handlers are invoked through java-invoke-local, either in a new process for each invocation, or through a java-invoke-local --server you started yourself, which serverless-offline doesn't manage.

For Node.js handlers which don't run in Docker, context.callbackWaitsForEmptyEventLoop is ignored: the response is sent as soon as the handler's promise settles or the callback is called, even if there is still pending work in the event loop. Unlike on AWS, that pending work is not frozen and keeps running.

Invoke Lambda

To use Lambda.invoke you need to set the lambda endpoint to the serverless-offline endpoint:

import { env } from "node:process"

import aws from "aws-sdk"

const lambda = new aws.Lambda({
  apiVersion: "2015-03-31",
  // endpoint needs to be set only if it deviates from the default
  endpoint: env.IS_OFFLINE ? "http://localhost:3002" : "https://lambda.us-east-1.amazonaws.com",
})

All your lambdas can then be invoked in a handler using

import { Buffer } from "node:buffer"

import aws from "aws-sdk"

const { stringify } = JSON

const lambda = new aws.Lambda({
  apiVersion: "2015-03-31",
  endpoint: "http://localhost:3002",
})

export async function handler() {
  const clientContextData = stringify({
    foo: "foo",
  })

  const payload = stringify({
    data: "foo",
  })

  const params = {
    ClientContext: Buffer.from(clientContextData).toString("base64"),
    // FunctionName is composed of: service name - stage - function name, e.g.
    FunctionName: "myServiceName-dev-invokedHandler",
    InvocationType: "RequestResponse",
    Payload: payload,
  }

  const response = await lambda.invoke(params).promise()

  return {
    body: stringify(response),
    statusCode: 200,
  }
}

You can also invoke using the AWS CLI by specifying --endpoint-url

aws lambda invoke /dev/null \
  --endpoint-url http://localhost:3002 \
  --function-name myServiceName-dev-invokedHandler

List of available function names and their corresponding serverless.yml function keys are listed after the server starts. This is important if you use a custom naming scheme for your functions as serverless-offline will use your custom name. The left side is the function's key in your serverless.yml (invokedHandler in the example below) and the right side is the function name that is used to call the function externally such as aws-sdk (myServiceName-dev-invokedHandler in the example below):

serverless offline
...
Starting Offline at stage dev (us-east-1)

Offline [http for lambda] listening on http://localhost:3002
Function names exposed for local invocation by aws-sdk:
   * invokedHandler: myServiceName-dev-invokedHandler

To list the available manual invocation paths exposed for targeting by aws-sdk and aws-cli, run serverless offline with the --debug flag. After the invoke server starts up, the full list of endpoints will be displayed:

serverless offline --debug
...
Starting Offline at stage dev (us-east-1)
...
Offline [http for lambda] listening on http://localhost:3002
Function names exposed for local invocation by aws-sdk:
   * invokedHandler: myServiceName-dev-invokedHandler
s:sls:plugin:serverless-offline: Lambda Invocation Routes (for AWS SDK or AWS CLI):
   * POST http://localhost:3002/2015-03-31/functions/myServiceName-dev-invokedHandler/invocations
s:sls:plugin:serverless-offline: Lambda Async Invocation Routes (for AWS SDK or AWS CLI):
   * POST http://localhost:3002/2014-11-13/functions/myServiceName-dev-invokedHandler/invoke-async/

You can manually target these endpoints with a REST client to debug your lambda function if you want to. Your POST JSON body will be the Payload passed to your function if you were to call it via aws-sdk.

The process.env.IS_OFFLINE variable

Will be "true" in your handlers when using serverless-offline.

Docker and Layers

To use layers with serverless-offline, you need to have the useDocker option set to true. This can be done either by using the --useDocker command, or in your serverless.yml like this:

custom:
  serverless-offline:
    useDocker: true

This will allow the docker container to look up any information about layers, download and use them. For this to work, you must be using:

• AWS as a provider, it won't work with other provider types.
• Layers that are compatible with your runtime.
• ARNs for layers. Local layers are not yet supported.
• A local AWS account set-up that can query and download layers.

If you're using least-privilege principals for your AWS roles, this policy should get you by:

{
  "Statement": [
    {
      "Action": "lambda:GetLayerVersion",
      "Effect": "Allow",
      "Resource": "arn:aws:lambda:*:*:layer:*:*"
    }
  ],
  "Version": "2012-10-17"
}

Once you run a function that boots up the Docker container, it'll look through the layers for that function, download them to your layers folder, and save a hash of your layers so it can be re-used in the future. You'll only need to re-download your layers if they change in the future. If you want your layers to re-download, simply remove your layers folder.

You should then be able to invoke functions as normal, and they're executed against the layers in your docker container.

Additional Options

There are 6 additional options available for Docker and Layer usage.

• dockerHost
• dockerHostServicePath
• dockerNetwork
• dockerReadOnly
• layersDir
• localLayers

dockerHost

When running Docker Lambda inside another Docker container, you may need to configure the host name for the host machine to resolve networking issues between Docker Lambda and the host. Typically in such cases you would set this to host.docker.internal.

dockerHostServicePath

When running Docker Lambda inside another Docker container, you may need to override the code path that gets mounted to the Docker Lambda container relative to the host machine. Typically in such cases you would set this to ${PWD}.

dockerNetwork

When running Docker Lambda inside another Docker container, you may need to override the network that Docker Lambda connects to in order to communicate with other containers.

dockerReadOnly

For certain programming languages and frameworks, it's desirable to be able to write to the filesystem for things like testing with local SQLite databases, or other testing-only modifications. For this, you can set dockerReadOnly: false, and this will allow local filesystem modifications. This does not strictly mimic AWS Lambda, as Lambda has a read-only filesystem, so this should be used as a last resort.

layersDir

By default layers are downloaded on a per-project basis, however, if you want to share them across projects, you can download them to a common place. For example, layersDir: /tmp/layers would allow them to be shared across projects. Make sure when using this setting that the directory you are writing layers to can be shared by docker.

localLayers

localLayers maps layer version ARNs from your deployed function configuration to local ZIP files or extracted directories. Relative paths are resolved from the service directory. Locally mapped layers do not require AWS credentials or network access; layers without a mapping continue to be downloaded from AWS.

custom:
  serverless-offline:
    useDocker: true
    localLayers:
      "arn:aws:lambda:us-east-1:123456789012:layer:custom-runtime:1": layers/custom-runtime.zip
      "arn:aws:lambda:us-east-1:123456789012:layer:tools:2": layers/tools

Local layer contents are included in the cache key, so editing a ZIP or a file in an extracted directory prepares a new cache entry on the next start. Multiple layers are extracted in function configuration order, matching AWS behavior when later layers overwrite files from earlier layers.

Authorizers

API keys

As defined in the Serverless Documentation you can use API Keys as a simple authentication method, by setting private: true on an http event. Requests to these endpoints need an x-api-key header with a valid key, or a Lambda authorizer which returns a valid key as usageIdentifierKey, otherwise they are answered with a 403.

The keys with a value in provider.apiGateway.apiKeys are valid keys. Keys given as a plain string, e.g. - myKey, are currently accepted as a key value as well, although Serverless uses the string as the key's name (see #1749). If no key value is configured this way, serverless-offline generates a random key on startup and prints it (Key with token: ...). Every valid key is accepted on every private endpoint.

The --apiKey option was removed in v11. To use a fixed key for local development only, choose the keys by stage:

custom:
  apiKeys:
    local:
      - name: myKey
        value: myLocalApiKeyForDevelopment
    prod:
      - name: myKey

provider:
  apiGateway:
    apiKeys: ${self:custom.apiKeys.${sls:stage}}

and run serverless offline start --stage local. Use --noAuth to turn off the API key checks.

Custom authorizers

Only custom authorizers are supported. Custom authorizers are executed before a Lambda function is executed and return an Error or a Policy document.

The Custom authorizer is passed an event object as below:

{
  "authorizationToken": "<Incoming bearer token>",
  "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>",
  "type": "TOKEN"
}

The methodArn does not include the Account id or API id.

The plugin only supports retrieving tokens from headers. You can configure the header as below:

"authorizer": {
  "authorizerResultTtlInSeconds": "0",
  "identitySource": "method.request.header.Authorization", // or method.request.header.SomeOtherHeader
  "type": "TOKEN"
}

Remote authorizers

You are able to mock the response from remote authorizers by setting the environment variable AUTHORIZER before running sls offline start

Example:

Unix: export AUTHORIZER='{"principalId": "123"}'

Windows: SET AUTHORIZER='{"principalId": "123"}'

JWT authorizers

For HTTP APIs, JWT authorizers defined in the serverless.yml can be used to validate the token and scopes in the token. However at this time, the signature of the JWT is not validated with the defined issuer. Since this is a security risk, this feature is only enabled with the --ignoreJWTSignature flag. Make sure to only set this flag for local development work.

Serverless plugin authorizers

If your authentication needs are custom and not satisfied by the existing capabilities of the Serverless offline project, you can inject your own authentication strategy. To inject a custom strategy for Lambda invocation, you define a custom variable under offline called customAuthenticationProvider in the serverless.yml file. The value of the custom variable will be used to require(your customAuthenticationProvider value) where the location is expected to return a function with the following signature.

offline:
  customAuthenticationProvider: ./path/to/custom-authentication-provider

// ./path/to/custom-authentication-provider.js

module.exports = function (endpoint, functionKey, method, path) {
  return {
    getAuthenticateFunction() {
      return {
        async authenticate(request, h) {
          // your implementation
        },
      }
    },

    name: "your strategy name",
    scheme: "your scheme name",
  }
}

A working example of injecting a custom authorization provider can be found in the project's integration tests under the folder custom-authentication.

Custom headers

You are able to use some custom headers in your request to gain more control over the requestContext object.

By doing this you are now able to change those values using a custom header. This can help you with easier authentication or retrieving the userId from a cognitoAuthenticationProvider value.

Environment variables

You are able to use environment variables to customize identity params in event context.

You can use serverless-dotenv-plugin to load environment variables from your .env file.

AWS API Gateway Features

Velocity Templates

Serverless doc ~ AWS doc

You can supply response and request templates for each function. This is optional. To do so, you will have to place function-specific template files in the same directory as your function file and add the .req.vm extension to the template filename. For example, if your function is in code-file: helloworld.js, your response template should be in file: helloworld.res.vm and your request template in file helloworld.req.vm.

Velocity nuances

Consider this requestTemplate for a POST endpoint:

"application/json": {
  "payload": "$input.json('$')",
  "id_json": "$input.json('$.id')",
  "id_path": "$input.path('$').id"
}

Now let's make a request with this body: { "id": 1 }

AWS parses the event as such:

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": "1" // Notice the string
}

Whereas Offline parses:

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": 1 // Notice the number
}

Accessing an attribute after using $input.path will return a string on AWS (expect strings like "1" or "true") but not with Offline (1 or true). You may find other differences.

CORS

Serverless doc

For HTTP APIs, the CORS configuration will work out of the box. Any CLI arguments passed in will be ignored.

For REST APIs, if the endpoint config has CORS set to true, the plugin will use the CLI CORS options for the associated route. Otherwise, no CORS headers will be added.

The Lambda invoke endpoint (lambdaPort) also follows the HTTP API CORS configuration when it is set, so a browser can call your functions with the AWS SDK. In that case, allowedHeaders must include the headers the AWS SDK sends, e.g. amz-sdk-invocation-id, amz-sdk-request, x-amz-content-sha256, x-amz-date and x-amz-user-agent. Without an HTTP API CORS configuration, the Lambda invoke endpoint allows any request header, and follows the corsAllowOrigin and corsDisallowCredentials options. Either way, it exposes the X-Amz-Function-Error and x-amzn-ErrorType response headers, which the AWS SDK reads to detect a failed invocation.

Catch-all Path Variables

AWS doc

Set greedy paths like /store/{proxy+} that will intercept requests made to /store/list-products, /store/add-product, etc...

ANY method

AWS doc

Works out of the box.

Lambda and Lambda Proxy Integrations

Serverless doc ~ AWS doc

Works out of the box. See examples in the manual_test directory.

HTTP Proxy

Serverless doc ~ AWS doc - AWS::ApiGateway::Method ~ AWS doc - AWS::ApiGateway::Resource

Example of enabling proxy:

custom:
  serverless-offline:
    resourceRoutes: true

or

    YourCloudFormationMethodId:
      Properties:
        ......
        Integration:
          Type: HTTP_PROXY
          Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
          ......
      Type: AWS::ApiGateway::Method

custom:
  serverless-offline:
    resourceRoutes:
      YourCloudFormationMethodId:
        Uri: "http://localhost:3001/assets/{proxy}"

Response parameters

AWS doc

You can set your response's headers using ResponseParameters.

May not work properly. Please PR. (Difficulty: hard?)

Example response velocity template:

"responseParameters": {
  "method.response.header.X-Powered-By": "Serverless", // a string
  "method.response.header.Warning": "integration.response.body", // the whole response
  "method.response.header.Location": "integration.response.body.some.key" // a pseudo JSON-path
},

WebSocket

To send a message back to a client, post it to the WebSocket server (port websocketPort, 3001 by default):

POST http://localhost:3001/@connections/{connectionId}

DELETE on the same URL disconnects the client.

Or, with the AWS SDK, from a handler:

import { env } from "node:process"

import {
  ApiGatewayManagementApiClient,
  PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi"

export async function handler(event) {
  const { connectionId, domainName, stage } = event.requestContext

  const client = new ApiGatewayManagementApiClient(
    env.IS_OFFLINE
      ? {
          // any value works, serverless-offline doesn't check them
          credentials: {
            accessKeyId: "offline",
            secretAccessKey: "offline",
          },
          endpoint: "http://localhost:3001",
        }
      : {
          endpoint: `https://${domainName}/${stage}`,
        },
  )

  await client.send(
    new PostToConnectionCommand({
      ConnectionId: connectionId,
      Data: "pong",
    }),
  )

  return {
    statusCode: 200,
  }
}

The AWS SDK signs every request, so it needs credentials even when it calls serverless-offline. Without the credentials option, it looks for your local AWS credentials (see Resource permissions and AWS profile), and throws CredentialsProviderError: Could not load credentials from any providers if there are none.

There's support for websocketsApiRouteSelectionExpression in its basic form: $request.body.x.y.z, where the default value is $request.body.action.

Debug process

Debug logs

Run serverless offline with the --debug flag to output additional information to the console, e.g. the Lambda invocation routes or why a request was rejected:

serverless offline start --debug

Interactive debugging

Since Serverless Framework v4, the serverless command is a native binary which starts the Node.js process running the framework and its plugins. Running node --inspect on serverless, or setting NODE_OPTIONS=--inspect, therefore doesn't debug your handlers.

Instead, open the inspector from within that process with the preLoadModules option. Create a file in your project:

// start-debugger.mjs
import inspector from "node:inspector"

inspector.open()

and preload it, using its absolute path:

serverless offline start --preLoadModules "$PWD/start-debugger.mjs"

The inspector listens on 127.0.0.1:9229, and you can attach any Node.js debugger to it, e.g. chrome://inspect in Chrome, or this launch configuration in Visual Studio Code:

{
  "name": "Attach to Serverless Offline",
  "port": 9229,
  "request": "attach",
  "type": "node"
}

Handlers run in worker threads by default. Debuggers which support Node.js worker threads, such as Visual Studio Code, attach to them automatically. If yours doesn't, use useInProcess.

On Windows, pass the path as a file URL, e.g. --preLoadModules "file:///C:/path/to/start-debugger.mjs".

Resource permissions and AWS profile

Lambda functions assume an IAM role during execution: the framework creates this role and sets all the permissions provided in the iamRoleStatements section of serverless.yml.

However, serverless offline makes use of your local AWS profile credentials to run the lambda functions and that might result in a different set of permissions. By default, the aws-sdk would load credentials for your default AWS profile specified in your configuration file.

You can change this profile directly in the code or by setting proper environment variables. Setting the AWS_PROFILE environment variable before calling serverless offline to a different profile would effectively change the credentials, e.g.

AWS_PROFILE=<profile> serverless offline

Simulation quality

This plugin simulates API Gateway for many practical purposes, good enough for development - but is not a perfect simulator. Specifically, Lambda currently runs on Node.js v20.x, v22.x and v24.x (AWS Docs), whereas Offline runs on your own runtime where no memory limits are enforced.

Usage with other plugins

When combining this plugin with other plugins there are a few things that you need to keep in mind.

You should run serverless offline start instead of serverless offline. The start command fires the offline:start:init and offline:start:end lifecycle hooks, which can be used by other plugins to process your code, add resources, perform cleanups, etc.

The order in which plugins are added to serverless.yml is relevant. Plugins are executed in order, so plugins that process your code or add resources should be added first so they are ready when this plugin starts.

For example:

plugins:
  - serverless-middleware # modifies some of your handler based on configuration
  - serverless-webpack # package your javascript handlers using webpack
  - serverless-dynamodb # adds a local dynamo db
  - serverless-offline # runs last so your code has been pre-processed and dynamo is ready

That works because all those plugins listen to the offline:start:init hook to do their processing. Similarly they listen to offline:start:end to perform cleanup (stop dynamo db, remove temporary files, etc).

Reloading handlers after code changes

Node.js, Python, Ruby and Docker handler instances are reused between invocations (see Handler lifecycle), so they keep running the code they loaded. To pick up code changes, either:

• use reloadHandler, which runs every invocation in a new instance. Every request then pays the cost of loading your code.
• or invoke the offline:functionsUpdated lifecycle event after your code changed. It terminates all instances, so the next invocation of each function loads the new code. Bundler plugins and file watchers can invoke it, e.g. serverless-offline-watcher:

plugins:
  - serverless-offline
  - serverless-offline-watcher

custom:
  serverless-offline-watcher:
    - path:
        - src/**/*
      hook:
        - offline:functionsUpdated

Neither works with useInProcess, as handler modules stay loaded until serverless-offline exits.

Credits and inspiration

This plugin was initially a fork of Nopik's Serverless-serve.

License

MIT

Contributing

Yes, thank you! This plugin is community-driven, most of its features are from different authors. Please update the docs and tests and add your name to the package.json file.

Contributors