@beforeyoubid/serverless-offline
Advanced tools
Emulate AWS λ and API Gateway locally when developing your Serverless project
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:
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.
invokeprocess.env.IS_OFFLINE variableFirst, add Serverless Offline to your project:
npm install serverless-offline --save-dev
Then inside your project's serverless.yml file add 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 wether 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.
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:
--allowCache Allows the code of lambda functions to cache if supported.
--apiKey Defines the API key value to be used for endpoints marked as private Defaults to a random hash.
--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 default Access-Control-Allow-Credentials header value will be passed as 'false'. Default: 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
--disableScheduledEvents Disables all scheduled events. Overrides configurations in serverless.yml.
--dockerHost The host name of Docker. Default: localhost
--dockerHostServicePath Defines service path which is used by SLS running inside 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
--hideStackTraces Hide the stack trace on lambda failure. Default: false
--host -o Host name to listen on. Default: localhost
--httpPort Http port to listen on. Default: 3000
--httpsProtocol -H 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. This should only be used for local development.
--lambdaPort Lambda http port to listen on. Default: 3002
--layersDir The directory layers should be stored in. Default: ${codeDir}/.serverless-offline/layers'
--noAuth Turns off all authorizers
--noPrependStageInUrl Don't prepend http routes with the stage.
--noStripTrailingSlashInUrl Don't strip trailing slash from http routes.
--noTimeout -t Disables the timeout feature.
--prefix -p Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead. Default: ''
--printOutput Turns on logging of your lambda outputs in the terminal.
--resourceRoutes Turns on loading of your HTTP proxy settings from serverless.yml
--useChildProcesses Run handlers in a child process
--useDocker Run handlers in a docker container.
--useWorkerThreads Uses worker threads for handlers. Requires node.js v11.7.0 or higher
--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
Any of the CLI options can be added to your serverless.yml. For example:
custom:
serverless-offline:
httpsProtocol: "dev-certs"
httpPort: 4000
stageVariables:
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:
serverless.yml or any of the default velocity template files.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 as input), whereas the plugin will answer 400 (malformed JSON).
Please consider explicitly setting your requests' Content-Type and using separate templates.invokeTo use Lambda.invoke you need to set the lambda endpoint to the serverless-offline endpoint:
const { Lambda } = require('aws-sdk')
const lambda = new Lambda({
apiVersion: '2015-03-31',
// endpoint needs to be set only if it deviates from the default, e.g. in a dev environment
// process.env.SOME_VARIABLE could be set in e.g. serverless.yml for provider.environment or function.environment
endpoint: process.env.SOME_VARIABLE
? 'http://localhost:3002'
: 'https://lambda.us-east-1.amazonaws.com',
})
All your lambdas can then be invoked in a handler using
exports.handler = async function () {
const params = {
// FunctionName is composed of: service name - stage - function name, e.g.
FunctionName: 'myServiceName-dev-invokedHandler',
InvocationType: 'RequestResponse',
Payload: JSON.stringify({ data: 'foo' }),
}
const response = await lambda.invoke(params).promise()
}
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
...
offline: Starting Offline: local/us-east-1.
offline: Offline [http for lambda] listening on http://localhost:3002
offline: 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, use SLS_DEBUG=* with serverless offline. After the invoke server starts up, full list of endpoints will be displayed:
SLS_DEBUG=* serverless offline
...
offline: Starting Offline: local/us-east-1.
...
offline: Offline [http for lambda] listening on http://localhost:3002
offline: Function names exposed for local invocation by aws-sdk:
* invokedHandler: myServiceName-dev-invokedHandler
[offline] Lambda Invocation Routes (for AWS SDK or AWS CLI):
* POST http://localhost:3002/2015-03-31/functions/myServiceName-dev-invokedHandler/invocations
[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 calling it via aws-sdk.
process.env.IS_OFFLINE variableWill be "true" in your handlers and thorough the plugin.
To use layers with serverless-offline, you need to have the useDocker option set to true. This can either be 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:
If you're using least-privilege principals for your AWS roles, this policy should get you by:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:GetLayerVersion",
"Resource": "arn:aws:lambda:*:*:layer:*:*"
}
]
}
Once you run a function that boots up the Docker container, it'll look through the layers for that function, download them in order to your layers folder, and save a hash of your layers so it can be re-used in 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.
There are 5 additional options available for Docker and Layer usage.
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.
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}.
When running Docker Lambda inside another Docker container, you may need to override network that Docker Lambda connects to in order to communicate with other containers.
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.
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.
As defined in the Serverless Documentation you can use API Keys as a simple authentication method.
Serverless-offline will emulate the behaviour of APIG and create a random token that's printed on the screen. With this token you can access your private methods adding x-api-key: generatedToken to your request header. All api keys will share the same token. To specify a custom token use the --apiKey cli option.
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:
{
"type": "TOKEN",
"authorizationToken": "<Incoming bearer token>",
"methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>"
}
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": {
"type": "TOKEN",
"identitySource": "method.request.header.Authorization", // or method.request.header.SomeOtherHeader
"authorizerResultTtlInSeconds": "0"
}
You are able to mock the response from remote authorizers by setting the environmental variable AUTHORIZER before running sls offline start
Example:
Unix:
export AUTHORIZER='{"principalId": "123"}'
Windows:
SET AUTHORIZER='{"principalId": "123"}'
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.
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 serverless-offline called authenticationProvider in the serverless.yml file. The value of the custom variable will be used to require(your authenticationProvider value) where the location is expected to return a function with the following signature.
module.exports = function (endpoint, functionKey, method, path) {
return {
name: 'your strategy name',
scheme: 'your scheme name',
getAuthenticateFunction: () => ({
async authenticate(request, h) {
// your implementation
},
}),
}
}
A working example of injecting a custom authorization provider can be found in the projects integration tests under the folder custom-authentication.
You are able to use some custom headers in your request to gain more control over the requestContext object.
| Header | Event key | Example |
|---|---|---|
| cognito-identity-id | event.requestContext.identity.cognitoIdentityId | |
| cognito-authentication-provider | event.requestContext.identity.cognitoAuthenticationProvider | |
| sls-offline-authorizer-override | event.requestContext.authorizer | { "iam": {"cognitoUser": { "amr": ["unauthenticated"], "identityId": "abc123" }}} |
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.
You are able to use environment variables to customize identity params in event context.
| Environment Variable | Event key |
|---|---|
| SLS_COGNITO_IDENTITY_POOL_ID | event.requestContext.identity.cognitoIdentityPoolId |
| SLS_ACCOUNT_ID | event.requestContext.identity.accountId |
| SLS_COGNITO_IDENTITY_ID | event.requestContext.identity.cognitoIdentityId |
| SLS_CALLER | event.requestContext.identity.caller |
| SLS_API_KEY | event.requestContext.identity.apiKey |
| SLS_API_KEY_ID | event.requestContext.identity.apiKeyId |
| SLS_COGNITO_AUTHENTICATION_TYPE | event.requestContext.identity.cognitoAuthenticationType |
| SLS_COGNITO_AUTHENTICATION_PROVIDER | event.requestContext.identity.cognitoAuthenticationProvider |
You can use serverless-dotenv-plugin to load environment variables from your .env file.
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.
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.
Set greedy paths like /store/{proxy+} that will intercept requests made to /store/list-products, /store/add-product, etc...
Works out of the box.
Works out of the box. See examples in the manual_test directory.
Serverless doc ~ AWS doc - AWS::ApiGateway::Method ~ AWS doc - AWS::ApiGateway::Resource
Example of enabling proxy:
custom:
serverless-offline:
resourceRoutes: true
or
YourCloudFormationMethodId:
Type: AWS::ApiGateway::Method
Properties:
......
Integration:
Type: HTTP_PROXY
Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
......
custom:
serverless-offline:
resourceRoutes:
YourCloudFormationMethodId:
Uri: 'http://localhost:3001/assets/{proxy}'
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
},
Usage in order to send messages back to clients:
POST http://localhost:3001/@connections/{connectionId}
Or,
const apiGatewayManagementApi = new AWS.ApiGatewayManagementApi({
apiVersion: '2018-11-29',
endpoint: 'http://localhost:3001',
});
apiGatewayManagementApi.postToConnection({
ConnectionId: ...,
Data: ...,
});
Where the event is received in the lambda handler function.
There's support for websocketsApiRouteSelectionExpression in it's basic form: $request.body.x.y.z, where the default value is $request.body.action.
Use serverless-webpack to compile and bundle your ES-next code
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.
Serverless offline plugin will respond to the overall framework settings and output additional information to the console in debug mode. In order to do this you will have to set the SLS_DEBUG environmental variable. You can run the following in the command line to switch to debug mode execution.
Unix:
export SLS_DEBUG=*
Windows:
SET SLS_DEBUG=*
Interactive debugging is also possible for your project if you have installed the node-inspector module and chrome browser. You can then run the following command line inside your project's root.
Initial installation:
npm install -g node-inspector
For each debug run:
node-debug sls offline
The system will start in wait status. This will also automatically start the chrome browser and wait for you to set breakpoints for inspection. Set the breakpoints as needed and, then, click the play button for the debugging to continue.
Depending on the breakpoint, you may need to call the URL path for your function in seperate browser window for your serverless function to be run and made available for debugging.
Lambda functions assume an IAM role during execution: the framework creates this role and set all the permission 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 you 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
Downstream plugins may tie into the before:offline:start:end hook to release resources when the server is shutting down.
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 v10.x, v12.x and v14.x (AWS Docs), whereas Offline runs on your own runtime where no memory limits are enforced.
Run serverless offline start. In comparison with serverless offline, the start command will fire an init and a end lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off resources.
Add plugins to your serverless.yml file:
plugins:
- serverless-webpack
- serverless-dynamodb-local
- serverless-offline # serverless-offline needs to be last in the list
This plugin was initially a fork of Nopik's Serverless-serve.
MIT
FAQs
Emulate AWS λ and API Gateway locally when developing your Serverless project
The npm package @beforeyoubid/serverless-offline receives a total of 2 weekly downloads. As such, @beforeyoubid/serverless-offline popularity was classified as not popular.
We found that @beforeyoubid/serverless-offline demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.