{"id":13576437,"url":"https://github.com/localstack/local-surf","last_synced_at":"2025-04-11T09:31:03.051Z","repository":{"id":150474887,"uuid":"606567351","full_name":"localstack/local-surf","owner":"localstack","description":"🏄 LocalSurf - a browser plugin to redirect AWS service calls to LocalStack","archived":false,"fork":false,"pushed_at":"2023-03-12T22:29:36.000Z","size":1162,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-05T12:33:43.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://localstack.cloud","language":"JavaScript","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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-02-25T21:52:11.000Z","updated_at":"2024-10-23T13:07:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"9d810d70-a0ca-4dd4-b9da-a4a112212ca8","html_url":"https://github.com/localstack/local-surf","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%2Flocal-surf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocal-surf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocal-surf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocal-surf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/local-surf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223464546,"owners_count":17149572,"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":[],"created_at":"2024-08-01T15:01:10.212Z","updated_at":"2024-11-07T05:32:16.391Z","avatar_url":"https://github.com/localstack.png","language":"JavaScript","readme":"# 🏄 LocalSurf - Browse AWS Web Applications Locally\n\nLocalSurf - a Chrome browser plugin to repoint AWS service calls to [LocalStack](https://localstack.cloud).\n\n⚠️ Please note that this plugin is experimental and still under active development.\n\n## Background\n\nWhen developing and testing AWS cloud Web applications locally with LocalStack, we need to make the browser connect to the local endpoint (`http://localhost:4566`) instead of the AWS production servers (`*.amazonaws.com`).\n\nThis can be achieved by explicitly setting the [`endpoint` attribute](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/specifying-endpoints.html) in the [AWS JavaScript SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Endpoint.html). Alternatively, it would be great if we could simply use the production code without changes, and have the browser make requests to LocalStack instead of AWS directly. This is where LocalSurf comes into play!\n\n## Installation\n\nThis extension is not yet available in the Chrome Web Store, but can be installed directly from source. Head over to `chrome://extensions/` in Chrome, then select `\"Load unpacked\"` and point to the directory where the source code files (this repo) are stored on disk.\n\nOnce installed, a new icon should appear in the Chrome extensions bar. When clicking on the icon, the plugin can be enabled/disabled by toggling the \"Enable local mode\" checkbox (see below).\n\n\u003cimg src=\"etc/localsurf-screenshot.png\" width=\"250\"/\u003e\n\n## Sample Demo\n\nTo illustrate how the plugin works, we use the AWS [Serverlesspresso](https://github.com/aws-samples/serverless-coffee-workshop) sample app. This app consists of various backend components (e.g., DynamoDB tables, Lambda functions, Cognito user pools, etc), as well as a hosted Web app user interface (UI) that can be used to interact with the backend components.\n\nWe can deploy the backend components to LocalStack directly, using the `samlocal` command line interface (CLI):\n```\n$ samlocal build\n$ samlocal deploy\n```\n\nOnce deployed, the `samlocal` CLI will print out a display app URL which will look similar to the following:\n```\nKey                 DisplayAppURI\nDescription         The URL for the Display App\nValue               https://workshop-display.serverlesscoffee.com/?region=us-east-1\u0026userPoolId=us-east-1_43c9800e64c84467aa0abdb102e226ef\u0026userPoolWebClientId=vr9aw2jr7iv36ezwaaqlzzkvbp\u0026poolId=us-east-1:95dc88d0-1029-48fe-ba7b-1e6a9741bfc5\u0026host=localhost.localstack.cloud\u0026orderManagerEndpoint=https://fapencq0ue.execute-api.amazonaws.com:4566/Prod\u0026APIGWEndpointValidatorService=https://psmdc7b1lv.execute-api.amazonaws.com:4566/Prod\u0026APIGWEndpointConfigService=https://hw7yw61ba7.execute-api.amazonaws.com:4566/Prod\n```\n\nWe can then open the URL in the browser and confirm the configurations in the form dialog (see below).\n\n\u003cimg src=\"etc/serverlesspresso-config.png\" width=\"600\"/\u003e\n\nOnce confirmed, we are being forwarded to a signin screen, which uses an AWS Cognito user pool to manage authentication:\n\n\u003cimg src=\"etc/serverlesspresso-login.png\" width=\"300\"/\u003e\n\nAfter clicking \"Sign In\" in this form, we can see that the browser makes a request to LocalStack (to `localhost.localstack.cloud`, which is a domain name that resolves to `127.0.0.1`).\n\n\u003cimg src=\"etc/chrome-networking.png\" width=\"600\"/\u003e\n\nThis sample demonstrates how we can take an existing Web application, without any modification, and make it talk to the LocalStack APIs directly from the browser via the LocalSurf plugin.\n\n## How it works\n\nThe plugin makes use of Chrome Extension [Content Scripts](https://developer.chrome.com/docs/extensions/mv3/content_scripts/), which run in the background in the browser - alongside the page scripts of the Web application itself. Whenever a Web application attempts to make a call to an AWS service (on `*.amazonaws.com` domains), then the call is intercepted and the page script forwards the request to the content script, which then performs the call against the LocalStack instance running in a Docker container on `localhost`.\n\n\u003cimg src=\"etc/localsurf-overview.png\" width=\"500\" /\u003e\n\nLocalSurf supports both, requests made via the `XMLHttpRequest` and via the `fetch(..)` browser APIs.\n\n## Disclaimer\n\nUse this extension at your own risk - it is provided on an as-is basis, **without** warranties or conditions of **any** kind. In particular, it is your obligation to ensure that the use of this extension is compliant with the user license agreement and the terms \u0026 conditions of Amazon Web Services (AWS) and their services.\n\n## License\n\nThis code is released under the Apache License Version 2.0 (see `LICENSE`).\n","funding_links":[],"categories":["Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocal-surf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Flocal-surf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocal-surf/lists"}