{"id":13431152,"url":"https://github.com/localstack/serverless-localstack","last_synced_at":"2025-05-14T05:10:42.538Z","repository":{"id":34221993,"uuid":"172154839","full_name":"localstack/serverless-localstack","owner":"localstack","description":"⚡ Serverless plugin for running against LocalStack","archived":false,"fork":false,"pushed_at":"2025-03-28T22:54:40.000Z","size":2234,"stargazers_count":531,"open_issues_count":17,"forks_count":89,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-11T20:43:39.384Z","etag":null,"topics":["aws","aws-lambda","serverless","serverless-framework"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-02-23T00:57:56.000Z","updated_at":"2025-04-04T04:22:12.000Z","dependencies_parsed_at":"2024-12-12T10:00:42.758Z","dependency_job_id":"c4bd05d1-181f-4322-9bf5-61f53be0d73b","html_url":"https://github.com/localstack/serverless-localstack","commit_stats":{"total_commits":167,"total_committers":39,"mean_commits":4.282051282051282,"dds":0.7485029940119761,"last_synced_commit":"4b5d09e72bd81783c4849987d85456a30da3d0d8"},"previous_names":["localstack/localstack-serverless"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fserverless-localstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fserverless-localstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fserverless-localstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fserverless-localstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/serverless-localstack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","serverless","serverless-framework"],"created_at":"2024-07-31T02:01:00.897Z","updated_at":"2025-05-14T05:10:42.480Z","avatar_url":"https://github.com/localstack.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/localstack/serverless-localstack.svg?branch=master)](https://travis-ci.org/localstack/serverless-localstack)\n\n# LocalStack Serverless Plugin\n\n[Serverless](https://serverless.com/) Plugin to support running against [Localstack](https://github.com/localstack/localstack).\n\nThis plugin allows Serverless applications to be deployed and tested on your local machine. Any requests to AWS to be redirected to a running LocalStack instance.\n\nPre-requisites:\n* LocalStack\n\n## Installation\n\nThe easiest way to get started is to install via npm.\n\n    npm install -g serverless\n    npm install --save-dev serverless-localstack\n\n## Configuring\n\nThe plugin can be configured via `serverless.yml`, or alternatively via environment variables.\n\nThere are two supported methods for configuring the endpoints, globally via the\n`host` property, or individually. These properties may be mixed, allowing for\nglobal override support while also override specific endpoints.\n\nA `host` or individual endpoints must be configured, or this plugin will be deactivated.\n\n### Configuration via serverless.yml\n\nPlease refer to the example configuration template below. (Please note that most configurations\nin the sample are optional and need not be specified.)\n\n```\nservice: myService\n\nplugins:\n  - serverless-localstack\n\ncustom:\n  localstack:\n    stages:\n      # list of stages for which the plugin should be enabled\n      - local\n    host: http://localhost  # optional - LocalStack host to connect to\n    edgePort: 4566  # optional - LocalStack edge port to connect to\n    autostart: true  # optional - Start LocalStack in Docker on Serverless deploy\n    networks: #optional - attaches the list of networks to the localstack docker container after startup\n      - host\n      - overlay\n      - my_custom_network\n    lambda:\n      # Enable this flag to improve performance\n      mountCode: true  # specify either \"true\", or a relative path to the root Lambda mount path\n    docker:\n      # Enable this flag to run \"docker ...\" commands as sudo\n      sudo: False\n      compose_file: /home/localstack_compose.yml # optional to use docker compose instead of docker or localstack cli\n  stages:\n    local:\n      ...\n```\n\n### Configuration via environment variables\n\nThe following environment variables can be configured (taking precedence over the values in `serverless.yml`):\n* `AWS_ENDPOINT_URL`: LocalStack endpoint URL to connect to (default: `http://localhost:4566`). This is the recommended configuration, and replaces the deprecated config options (`EDGE_PORT`/`LOCALSTACK_HOSTNAME`/`USE_SSL`) below.\n* `EDGE_PORT`: LocalStack edge port to connect to (deprecated; default: `4566`)\n* `LOCALSTACK_HOSTNAME`: LocalStack host name to connect to (deprecated; default: `localhost`)\n* `USE_SSL`: Whether to use SSL/HTTPS when connecting to the LocalStack endpoint (deprecated)\n\n### Activating the plugin for certain stages\n\nNote the `stages` attribute in the config above. The `serverless-localstack` plugin gets activated if either:\n  1. the serverless stage (explicitly defined or default stage \"dev\") is included in the `stages` config; or\n  2. serverless is invoked without a `--stage` flag (default stage \"dev\") and no `stages` config is provided\n\n### Mounting Lambda code for better performance\n\nNote that the `localstack.lambda.mountCode` flag above will mount the local directory into\nthe Docker container that runs the Lambda code in LocalStack. You can either specify the boolean\nvalue `true` (to mount the project root folder), or a relative path to the root Lambda mount path\nwithin your project (e.g., `./functions`).\n\nIf you remove this flag, your Lambda code is deployed in the traditional way which is more in\nline with how things work in AWS, but also comes with a performance penalty: packaging the code,\nuploading it to the local S3 service, downloading it in the local Lambda API, extracting\nit, and finally copying/mounting it into a Docker container to run the Lambda. Mounting code\nfrom multiple projects is not supported with simple configuration, and you must use the\n`autostart` feature, as your code will be mounted in docker at start up. If you do need to\nmount code from multiple serverless projects, manually launch\nlocalstack with volumes specified. For example:\n\n```sh\nlocalstack start --docker -d \\\n  -v /path/to/project-a:/path/to/project-a \\\n  -v /path/to/project-b:/path/to/project-b\n```\n\nIf you use either `serverless-webpack`, `serverless-plugin-typescript`, or `serverless-esbuild`, `serverless-localstack`\nwill detect it and modify the mount paths to point to your output directory. You will need to invoke\nthe build command in order for the mounted code to be updated. (eg: `serverless webpack`). There is no\n`--watch` support for this out of the box, but could be accomplished using nodemon:\n\n```sh\nnpm i --save-dev nodemon\n```\n\nWebpack example's `package.json`:\n\n```json\n  \"scripts\": {\n    \"build\": \"serverless webpack --stage local\",\n    \"deploy\": \"serverless deploy --stage local\",\n    \"watch\": \"nodemon -w src -e '.*' -x 'npm run build'\",\n    \"start\": \"npm run deploy \u0026\u0026 npm run watch\"\n  },\n```\n\n```sh\nnpm run start\n```\n\n#### A note on using webpack\n\n`serverless-webpack` is supported, with code mounting. However, there are some assumptions\nand configuration requirements. First, your output directory must be `.webpack`. Second, you must retain\nyour output directory contents. You can do this by modifying the `custom \u003e webpack` portion of your\nserverless configuration file.\n\n```yml\ncustom:\n  webpack:\n    webpackConfig: webpack.config.js\n    includeModules: true\n    keepOutputDirectory: true\n  localstack:\n    stages:\n      - local\n    lambda:\n      mountCode: true\n    autostart: true\n```\n\n### Environment Configurations\n\n* `LAMBDA_MOUNT_CWD`: Allow users to define a custom working directory for Lambda mounts.\n   For example, when deploying a Serverless app in a Linux VM (that runs Docker) on a\n   Windows host where the `-v \u003clocal_dir\u003e:\u003ccont_dir\u003e` flag to `docker run` requires us\n   to specify a `local_dir` relative to the Windows host file system that is mounted\n   into the VM (e.g., `\"c:/users/guest/...\"`).\n* `LAMBDA_EXECUTOR`: Executor type to use for running Lambda functions (default `docker`) -\n   see [LocalStack repo](https://github.com/localstack/localstack)\n* `LAMBDA_REMOTE_DOCKER`: Whether to assume that we're running Lambda containers against\n   a remote Docker daemon (default `false`) - see [LocalStack repo](https://github.com/localstack/localstack)\n* `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [Hot Reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading/).\n\n### Only enable serverless-localstack for the listed stages\n* ```serverless deploy --stage local``` would deploy to LocalStack.\n* ```serverless deploy --stage production``` would deploy to aws.\n\n```\nservice: myService\n\nplugins:\n  - serverless-localstack\n\ncustom:\n  localstack:\n    stages:\n      - local\n      - dev\n    endpointFile: path/to/file.json\n```\n\n## LocalStack\n\nFor full documentation, please refer to https://github.com/localstack/localstack\n\n## Contributing\n\nSetting up a development environment is easy using Serverless' plugin framework.\n\n### Clone the Repo\n\n```\ngit clone https://github.com/localstack/serverless-localstack\n```\n\n### Setup your project\n\n```\ncd /path/to/serverless-localstack\nnpm link\n\ncd myproject\nnpm link serverless-localstack\n```\n\n### Optional Debug Flag\n\nAn optional debug flag is supported via `serverless.yml` that will enable additional debug logs.\n\n```\ncustom:\n  localstack:\n    debug: true\n```\n\n## Change Log\n* v1.3.1: prevent the mounting of code if the Lambda uses an ECR Image\n* v1.3.0: add support for built-in Esbuild in Serverless Framework v4 #267\n* v1.2.1: Fix custom-resource bucket compatibility with serverless \u003e3.39.0, continue improving support for `AWS_ENDPOINT_URL`\n* v1.2.0: Add docker-compose config and fix autostart when plugin is not active \n* v1.1.3: Fix replacing host from environment variable `AWS_ENDPOINT_URL`\n* v1.1.2: Unify construction of target endpoint URL, add support for configuring `AWS_ENDPOINT_URL`\n* v1.1.1: Fix layer deployment if `mountCode` is enabled by always packaging and deploying\n* v1.1.0: Fix SSM environment variables resolving issues with serverless v3, change default for `BUCKET_MARKER_LOCAL` to `hot-reload`\n* v1.0.6: Add `BUCKET_MARKER_LOCAL` configuration for customizing S3 bucket for lambda mount and [Hot Reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading/).\n* v1.0.5: Fix S3 Bucket LocationConstraint issue when the provider region is `us-east-1`\n* v1.0.4: Fix IPv4 fallback check to prevent IPv6 connection issue with `localhost` on macOS\n* v1.0.3: Set S3 Path addressing for internal Serverless Custom Resources - allow configuring S3 Events Notification for functions\n* v1.0.2: Add check to prevent IPv6 connection issue with `localhost` on MacOS\n* v1.0.1: Add support for Serverless projects with esbuild source config; enable config via environment variables\n* v1.0.0: Allow specifying path for mountCode, to point to a relative Lambda mount path\n* v0.4.36: Add patch to avoid \"TypeError\" in AwsDeploy plugin on Serverless v3.4.0+\n* v0.4.35: Add config option to connect to additional Docker networks\n* v0.4.33: Fix parsing StepFunctions endpoint if the endpointInfo isn't defined\n* v0.4.32: Add endpoint to AWS credentials for compatibility with serverless-domain-manager plugin\n* v0.4.31: Fix format of API GW endpoints printed in stack output\n* v0.4.30: Fix plugin for use with Serverless version 2.30+\n* v0.4.29: Add missing service endpoints to config\n* v0.4.28: Fix plugin activation for variable refs in profile names\n* v0.4.27: Fix loading of endpoints file with variable references to be resolved\n* v0.4.26: Fix resolution of template variables during plugin initialization\n* v0.4.25: Use single edge port instead of deprecated service-specific ports\n* v0.4.24: Fix resolving of stage/profiles via variable expansion\n* v0.4.23: Fix config loading to enable file imports; fix output of API endpoints if plugin is not activated; enable SSM and CF output refs by performing early plugin loading\n* v0.4.21: Fix integration with `serverless-plugin-typescript` when `mountCode` is enabled\n* v0.4.20: Use `LAMBDA_EXECUTOR`/`LAMBDA_REMOTE_DOCKER` configurations from environment\n* v0.4.19: Fix populating local test credentials in AWS provider\n* v0.4.18: Fix output of API Gateway endpoints; add port mappings; fix config init code\n* v0.4.17: Enable configuration of `$START_WEB`\n* v0.4.16: Add option for running Docker as sudo; add fix for downloadPackageArtifacts\n* v0.4.15: Enable plugin on aws:common:validate events\n* v0.4.14: Initialize LocalStack using hooks for each \"before:\" event\n* v0.4.13: Add endpoint for SSM; patch serverless-secrets plugin; allow customizing $DOCKER_FLAGS\n* v0.4.12: Fix Lambda packaging for `mountCode:false`\n* v0.4.11: Add polling loop for starting LocalStack in Docker\n* v0.4.8: Auto-create deployment bucket; autostart LocalStack in Docker\n* v0.4.7: Set S3 path addressing; add eslint to CI config\n* v0.4.6: Fix port mapping for service endpoints\n* v0.4.5: Fix config to activate or deactivate the plugin for certain stages\n* v0.4.4: Add `LAMBDA_MOUNT_CWD` configuration for customizing Lambda mount dir\n* v0.4.3: Support local mounting of Lambda code to improve performance\n* v0.4.0: Add support for local STS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Fserverless-localstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Fserverless-localstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Fserverless-localstack/lists"}