{"id":18636668,"url":"https://github.com/localstack/localstack-extensions","last_synced_at":"2025-10-24T01:05:26.223Z","repository":{"id":43081901,"uuid":"510815882","full_name":"localstack/localstack-extensions","owner":"localstack","description":"🧩 Extend and customize LocalStack with LocalStack Extensions (beta)","archived":false,"fork":false,"pushed_at":"2025-03-25T14:06:51.000Z","size":1497,"stargazers_count":40,"open_issues_count":6,"forks_count":11,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-29T07:02:49.388Z","etag":null,"topics":["localstack","localstack-extensions","plugins"],"latest_commit_sha":null,"homepage":"https://docs.localstack.cloud/user-guide/extensions/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-05T16:34:06.000Z","updated_at":"2025-03-25T14:06:56.000Z","dependencies_parsed_at":"2024-01-09T15:00:32.964Z","dependency_job_id":"ea7adc55-5f6f-43bc-a583-06b236c29dca","html_url":"https://github.com/localstack/localstack-extensions","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/localstack-extensions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305930,"owners_count":20917207,"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":["localstack","localstack-extensions","plugins"],"created_at":"2024-11-07T05:31:04.919Z","updated_at":"2025-10-24T01:05:26.218Z","avatar_url":"https://github.com/localstack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LocalStack Extensions (Preview)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/localstack/localstack-extensions/assets/3996682/bba99a4a-e479-4da9-ba3e-1ea9ce80f9b7\" alt=\"LocalStack Extensions\"\u003e\n\u003c/p\u003e\n\n\nWith LocalStack 1.0 we have introduced LocalStack Extensions that allow\ndevelopers to extend and customize LocalStack. Both the feature and the API\nare currently in preview and may be subject to change.\n\n## Using Extensions\n\nExtensions are a LocalStack Pro feature.\nTo use and install extensions, use the CLI to first log in to your account\n\n```console\n$ localstack auth login\nPlease provide your login credentials below\nUsername: ...\n```\n\n```console\n$ localstack extensions --help\n\nUsage: localstack extensions [OPTIONS] COMMAND [ARGS]...\n\n  (Preview) Manage LocalStack extensions.\n\n  LocalStack Extensions allow developers to extend and customize LocalStack.\n  The feature and the API are currently in a preview stage and may be subject to change.\n\n  Visit https://docs.localstack.cloud/references/localstack-extensions/\n  for more information on LocalStack Extensions.\n\nOptions:\n  -v, --verbose  Print more output\n  -h, --help     Show this message and exit.\n\nCommands:\n  dev        Developer tools for developing LocalStack extensions.\n  init       Initialize the LocalStack extensions environment.\n  install    Install a LocalStack extension.\n  list       List installed extension.\n  uninstall  Remove a LocalStack extension.\n\n```\n\nTo install an extension, specify the name of the pip dependency that contains\nthe extension. For example, for the official Stripe extension, you can either\nuse the package distributed on pypi:\n\n```console\n$ localstack extensions install localstack-extension-httpbin\n```\n\nor you can install the latest version directly from this Git repository\n\n```console\n$ localstack extensions install \"git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-httpbin\u0026subdirectory=httpbin\"\n```\n\n## Official LocalStack Extensions\n\nHere is the current list of extensions developed by the LocalStack team and their support status.\nYou can install the respective extension by calling `localstack install \u003cInstall name\u003e`.\n\n| Extension                                                                                          | Install name | Version | Support status |\n|----------------------------------------------------------------------------------------------------| ------------ |---------| -------------- |\n| [AWS Proxy](https://github.com/localstack/localstack-extensions/tree/main/aws-proxy)               | localstack-extension-aws-proxy | 0.2.1   | Experimental |\n| [Diagnosis Viewer](https://github.com/localstack/localstack-extensions/tree/main/diagnosis-viewer) | localstack-extension-diagnosis-viewer | 0.1.0   | Stable |\n| [Hello World](https://github.com/localstack/localstack-extensions/tree/main/hello-world)           | localstack-extension-hello-world | 0.1.0   | Stable |\n| [httpbin](https://github.com/localstack/localstack-extensions/tree/main/httpbin)                   | localstack-extension-httpbin | 0.1.0   | Stable |\n| [MailHog](https://github.com/localstack/localstack-extensions/tree/main/mailhog)                   | localstack-extension-mailhog | 0.1.0   | Stable |\n| [Miniflare](https://github.com/localstack/localstack-extensions/tree/main/miniflare)               | localstack-extension-miniflare | 0.1.0   | Experimental |\n| [Stripe](https://github.com/localstack/localstack-extensions/tree/main/stripe)                     | localstack-extension-stripe | 0.2.0   | Stable |\n| [Terraform Init](https://github.com/localstack/localstack-extensions/tree/main/terraform-init)     | localstack-extension-terraform-init | 0.2.0   | Experimental |\n\n\n## Developing Extensions\n\nThis section provides a brief overview of how to develop your own extensions.\n\n### The extensions API\n\nLocalStack exposes a Python API for building extensions that can be found in\nthe core codebase in\n[`localstack.extensions.api`](https://github.com/localstack/localstack/tree/master/localstack-core/localstack/extensions/api).\n\nThe basic interface to implement is as follows:\n\n```python\nclass Extension(BaseExtension):\n    \"\"\"\n    An extension that is loaded into LocalStack dynamically. The method\n    execution order of an extension is as follows:\n\n    - on_extension_load\n    - on_platform_start\n    - update_gateway_routes\n    - update_request_handlers\n    - update_response_handlers\n    - on_platform_ready\n    - on_platform_shutdown\n    \"\"\"\n\n    namespace: str = \"localstack.extensions\"\n    \"\"\"The namespace of all basic localstack extensions.\"\"\"\n\n    name: str\n    \"\"\"The unique name of the extension set by the implementing class.\"\"\"\n\n    def on_extension_load(self):\n        \"\"\"\n        Called when LocalStack loads the extension.\n        \"\"\"\n        pass\n\n    def on_platform_start(self):\n        \"\"\"\n        Called when LocalStack starts the main runtime.\n        \"\"\"\n        pass\n\n    def on_platform_shutdown(self):\n        \"\"\"\n        Called when LocalStack is shutting down. Can be used to close any resources (threads, processes, sockets, etc.).\n        \"\"\"\n        pass\n\n    def update_gateway_routes(self, router: Router[RouteHandler]):\n        \"\"\"\n        Called with the Router attached to the LocalStack gateway. Overwrite this to add or update routes.\n        :param router: the Router attached in the gateway\n        \"\"\"\n        pass\n\n    def update_request_handlers(self, handlers: CompositeHandler):\n        \"\"\"\n        Called with the custom request handlers of the LocalStack gateway. Overwrite this to add or update handlers.\n        :param handlers: custom request handlers of the gateway\n        \"\"\"\n        pass\n\n    def update_response_handlers(self, handlers: CompositeResponseHandler):\n        \"\"\"\n        Called with the custom response handlers of the LocalStack gateway. Overwrite this to add or update handlers.\n        :param handlers: custom response handlers of the gateway\n        \"\"\"\n        pass\n\n    def on_platform_ready(self):\n        \"\"\"\n        Called when LocalStack is ready and the Ready marker has been printed.\n        \"\"\"\n        pass\n```\n\nA minimal example would look like this:\n\n```python\nimport logging\nfrom localstack.extensions.api import Extension\n\nLOG = logging.getLogger(__name__)\n\nclass ReadyAnnouncerExtension(Extension):\n    name = \"my_ready_announcer\"\n\n    def on_platform_ready(self):\n    \tLOG.info(\"my plugin is loaded and localstack is ready to roll!\")\n```\n\n### Package your Extension\n\nYour extensions needs to be packaged as a Python distribution with a\n`setup.cfg` or `setup.py` config. LocalStack uses the\n[Plux](https://github.com/localstack/plux) code loading framework to load your\ncode from a Python [entry point](https://packaging.python.org/en/latest/specifications/entry-points/).\nYou can either use Plux to discover the entrypoints from your code when\nbuilding and publishing your distribution, or manually define them as in the\nexample below.\n\nA minimal `setup.cfg` for the extension above could look like this:\n\n```ini\n[metadata]\nname = localstack-extension-ready-announcer\ndescription = LocalStack extension that logs when LocalStack is ready to receive requests\nauthor = Your Name\nauthor_email = your@email.com\nurl = https://link-to-your-project\n\n[options]\nzip_safe = False\npackages = find:\ninstall_requires =\n    localstack\u003e=1.0.0\n\n[options.entry_points]\nlocalstack.extensions =\n    my_ready_announcer = localstack_announcer.extension:ReadyAnnouncerExtension\n```\n\nThe entry point group is the Plux namespace `locastack.extensions`, and the\nentry point name is the plugin name `my_ready_announcer`. The object\nreference points to the plugin class.\n\n\n### Using the extensions CLI\n\nThe extensions CLI has a set of developer commands that allow you to create new extensions, and toggle local dev mode for extensions.\nExtensions that are toggled for developer mode will be mounted into the localstack container so you don't need to re-install them every time you change something.\n\n```console\nUsage: localstack extensions dev [OPTIONS] COMMAND [ARGS]...\n\n  Developer tools for developing Localstack extensions\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  disable  Disables an extension on the host for developer mode.\n  enable   Enables an extension on the host for developer mode.\n  list     List LocalStack extensions for which dev mode is enabled.\n  new      Create a new LocalStack extension from the official extension...\n```\n\n#### Creating a new extensions\n\nFirst, create a new extensions from a template:\n\n```console\n % localstack extensions dev new\nproject_name [My LocalStack Extension]: \nproject_short_description [All the boilerplate you need to create a LocalStack extension.]: \nproject_slug [my-localstack-extension]: \nmodule_name [my_localstack_extension]: \nfull_name [Jane Doe]: \nemail [jane@example.com]: \ngithub_username [janedoe]: \nversion [0.1.0]: \n```\n\nThis will create a new python project with the following layout:\n\n```\nmy-localstack-extension\n├── Makefile\n├── my_localstack_extension\n│   ├── extension.py\n│   └── __init__.py\n├── README.md\n├── setup.cfg\n└── setup.py\n```\n\nThen run `make install` in the newly created project to make a distribution package.\n\n#### Start LocalStack with the extension\n\nTo start LocalStack with the extension in dev mode, first enable it by running:\n\n```console\nlocalstack extensions dev enable ./my-localstack-extension\n```\n\nThen, start LocalStack with `EXTENSION_DEV_MODE=1`\n\n```console\nEXTENSION_DEV_MODE=1 LOCALSTACK_API_KEY=... localstack start\n```\n\nIn the LocalStack logs you should then see something like:\n```\n==================================================\n👷 LocalStack extension developer mode enabled 🏗\n- mounting extension /opt/code/extensions/my-localstack-extension\nResuming normal execution, ...\n==================================================\n```\n\nNow, when you make changes to your extensions, you just need to restart LocalStack and the changes will be picked up by LocalStack automatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Flocalstack-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-extensions/lists"}