{"id":13645229,"url":"https://github.com/nlepage/go-wasm-http-server","last_synced_at":"2025-05-16T01:04:55.631Z","repository":{"id":45778175,"uuid":"224222120","full_name":"nlepage/go-wasm-http-server","owner":"nlepage","description":"Embed your Go HTTP handlers in a ServiceWorker and emulate an HTTP server!","archived":false,"fork":false,"pushed_at":"2025-02-13T09:42:08.000Z","size":25444,"stargazers_count":375,"open_issues_count":3,"forks_count":29,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-08T12:05:34.604Z","etag":null,"topics":["golang","http-server","service-worker","serviceworker","wasm"],"latest_commit_sha":null,"homepage":"","language":"Go","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/nlepage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["nlepage"]}},"created_at":"2019-11-26T15:16:29.000Z","updated_at":"2025-04-01T08:55:48.000Z","dependencies_parsed_at":"2025-03-18T07:11:07.810Z","dependency_job_id":"741e7fb5-c664-4bfd-a6ac-140a06ca43b8","html_url":"https://github.com/nlepage/go-wasm-http-server","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nlepage%2Fgo-wasm-http-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nlepage%2Fgo-wasm-http-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nlepage%2Fgo-wasm-http-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nlepage%2Fgo-wasm-http-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nlepage","download_url":"https://codeload.github.com/nlepage/go-wasm-http-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"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":["golang","http-server","service-worker","serviceworker","wasm"],"created_at":"2024-08-02T01:02:31.653Z","updated_at":"2025-05-16T01:04:55.596Z","avatar_url":"https://github.com/nlepage.png","language":"Go","funding_links":["https://github.com/sponsors/nlepage"],"categories":["Go"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eWelcome to go-wasm-http-server 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/nlepage/go-wasm-http-server#section-documentation\"\u003e\n    \u003cimg src=\"https://pkg.go.dev/badge/github.com/nlepage/go-wasm-http-server.svg\" alt=\"Go Reference\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/nlepage/go-wasm-http-server/blob/master/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: Apache 2.0\" src=\"https://img.shields.io/badge/License-Apache--2.0-yellow.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Embed your Go HTTP handlers in a ServiceWorker (using [WebAssembly](https://mdn.io/WebAssembly/)) and emulate an HTTP server!\n\n## Examples\n\n - [Hello example](https://nlepage.github.io/go-wasm-http-server/hello) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello))\n - [Hello example with state](https://nlepage.github.io/go-wasm-http-server/hello-state) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-state))\n - [Hello example with state and keepalive](https://nlepage.github.io/go-wasm-http-server/hello-state-keepalive) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-state-keepalive))\n - [Hello example with Server Sent Events](https://nlepage.github.io/go-wasm-http-server/hello-sse/) ([sources](https://nlepage.github.io/go-wasm-http-server/hello-sse/))\n - [😺 Catption generator example](https://nlepage.github.io/catption/wasm) ([sources](https://github.com/nlepage/catption/tree/wasm))\n - [Random password generator web server](https://nlepage.github.io/random-password-please/) ([sources](https://github.com/nlepage/random-password-please) forked from [jbarham/random-password-please](https://github.com/jbarham/random-password-please))\n - [Server fallbacks, and compiling with TinyGo](https://nlepage.github.io/go-wasm-http-server/tinygo/) (runs locally; see [sources \u0026 readme](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/tinygo#readme) for how to run this example)\n\n## How?\n\nBelow is a talk given at the Go devroom of FOSDEM 2021 explaining how `go-wasm-http-server` works.\n\n\u003e [!WARNING]  \n\u003e `go-wasm-http-server` has suffered major changes since this talk, be aware that it is not accurate anymore on several aspects.\n\u003e Please refer to the documentation below for up to date usage of `go-wasm-http-server`.\n\n[![Deploy a Go HTTP server in your browser Youtube link](https://raw.githubusercontent.com/nlepage/go-wasm-http-talk/main/youtube.png)](https://youtu.be/O2RB_8ircdE)\n\nThe slides are available [here](https://nlepage.github.io/go-wasm-http-talk/).\n\n## Why?\n\n`go-wasm-http-server` can help you put up a demonstration for a project without actually running a Go HTTP server.\n\n## Requirements\n\n`go-wasm-http-server` requires you to build your Go application to WebAssembly, so you need to make sure your code is compatible:\n- no C bindings\n- no System dependencies such as file system or network (database server for example)\n- For smaller WASM blobs, your code may also benefit from being compatible with, and compiled by, [TinyGo](https://tinygo.org/docs/reference/lang-support/stdlib/). See the TinyGo specific details below.\n\n## Usage\n\n### Step 1: Build to `js/wasm`\n\nIn your Go code, replace [`http.ListenAndServe()`](https://pkg.go.dev/net/http#ListenAndServe) (or [`net.Listen()`](https://pkg.go.dev/net#Listen) + [`http.Serve()`](https://pkg.go.dev/net/http#Serve)) by [wasmhttp.Serve()](https://pkg.go.dev/github.com/nlepage/go-wasm-http-server#Serve):\n\n📄 `server.go`\n```go\n//go:build !js \u0026\u0026 !wasm\n\npackage main\n\nimport (\n    \"net/http\"\n)\n\nfunc main() {\n    // Define handlers...\n\n    http.ListenAndServe(\":8080\", nil)\n}\n```\n\nbecomes:\n\n📄 `server_js_wasm.go`\n```go\n//go:build js \u0026\u0026 wasm\n\npackage main\n\nimport (\n    wasmhttp \"github.com/nlepage/go-wasm-http-server/v2\"\n)\n\nfunc main() {\n    // Define handlers...\n\n    wasmhttp.Serve(nil)\n}\n```\n\nYou may want to use build tags as shown above (or file name suffixes) in order to be able to build both to WebAssembly and other targets.\n\nThen build your WebAssembly binary:\n\n```sh\n# To compile with Go\nGOOS=js GOARCH=wasm go build -o server.wasm .\n\n# To compile with TinyGo, if your code is compatible\nGOOS=js GOARCH=wasm tinygo build -o server.wasm  .\n```\n\n### Step 2: Create ServiceWorker file\n\nFirst, check the version of Go/TinyGo you compiled your wasm with:\n\n```sh\n$ go version\ngo version go1.23.4 darwin/arm64\n#          ^------^\n\n$ tinygo version\ntinygo version 0.35.0 darwin/arm64 (using go version go1.23.4 and LLVM version 18.1.2)\n#              ^----^\n```\n\nCreate a ServiceWorker file with the following code:\n\n📄 `sw.js`\n```js\n// Note the 'go.1.23.4' below, that matches the version you just found:\nimportScripts('https://cdn.jsdelivr.net/gh/golang/go@go1.23.4/misc/wasm/wasm_exec.js')\n// If you compiled with TinyGo then, similarly, use:\nimportScripts('https://cdn.jsdelivr.net/gh/tinygo-org/tinygo@0.35.0/targets/wasm_exec.js')\n\nimportScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v2.2.1/sw.js')\n\nregisterWasmHTTPListener('path/to/server.wasm')\n```\n\nBy default the server will deploy at the ServiceWorker's scope root, check [`registerWasmHTTPListener()`'s API](https://github.com/nlepage/go-wasm-http-server#registerwasmhttplistenerwasmurl-options) for more information.\n\nYou may want to add these additional event listeners in your ServiceWorker:\n\n```js\n// Skip installed stage and jump to activating stage\naddEventListener('install', (event) =\u003e {\n  event.waitUntil(skipWaiting())\n})\n\n// Start controlling clients as soon as the SW is activated\naddEventListener('activate', event =\u003e {\n  event.waitUntil(clients.claim())\n})\n```\n\n### Step 3: Register the ServiceWorker\n\nIn your web page(s), register the ServiceWorker:\n\n```html\n\u003cscript\u003e\n  // By default the ServiceWorker's scope will be \"server/\"\n  navigator.serviceWorker.register('server/sw.js')\n\u003c/script\u003e\n```\n\nNow your web page(s) may start fetching from the server:\n\n```js\n// The server will receive a request for \"/path/to/resource\"\nfetch('server/path/to/resource').then(res =\u003e {\n  // use response...\n})\n```\n\n## API\n\nFor Go API see [pkg.go.dev/github.com/nlepage/go-wasm-http-server](https://pkg.go.dev/github.com/nlepage/go-wasm-http-server#section-documentation)\n\n### JavaScript API\n\n### `registerWasmHTTPListener(wasmUrl, options)`\n\nInstantiates and runs the WebAssembly module at `wasmUrl`, and registers a fetch listener forwarding requests to the WebAssembly module's server.\n\n⚠ This function must be called only once in a ServiceWorker, if you want to register several servers you must use several ServiceWorkers.\n\nThe server will be \"deployed\" at the root of the ServiceWorker's scope by default, `base` may be used to deploy the server at a subpath of the scope.\n\nSee [ServiceWorkerContainer.register()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register) for more information about the scope of a ServiceWorker.\n\n#### `wasmUrl`\n\nURL string of the WebAssembly module, example: `\"path/to/my-module.wasm\"`.\n\n#### `options`\n\nAn optional object containing:\n\n- `base` (`string`): Base path of the server, relative to the ServiceWorker's scope.\n- `cacheName` (`string`): Name of the [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to store the WebAssembly binary.\n- `args` (`string[]`): Arguments for the WebAssembly module.\n- `passthrough` (`(request: Request): boolean`): Optional callback to allow passing the request through to network.\n\n## \u003cabbr title=\"Frequently Asked Questions\"\u003eFAQ\u003c/abbr\u003e ❓\n\n### Are WebSockets supported?\n\nNo, WebSockets aren’t and won’t be supported, because Service Workers cannot intercept websocket connections.\n\nHowever [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), which is an alternative to WebSockets, are supported, you can find the code for an example [here](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-sse) and the demo [here](https://nlepage.github.io/go-wasm-http-server/hello-sse/).\n\n### Is it compatible with TinyGo?\n\nYes, an example and some specific information is available [here](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/tinygo).\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://byjp.me/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/42999?v=4?s=100\" width=\"100px;\" alt=\"JP Hastings-Edrei\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJP Hastings-Edrei\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nlepage/go-wasm-http-server/commits?author=jphastings\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/nlepage/go-wasm-http-server/commits?author=jphastings\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#example-jphastings\" title=\"Examples\"\u003e💡\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://recolude.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/9094977?v=4?s=100\" width=\"100px;\" alt=\"Eli Davis\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eEli Davis\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nlepage/go-wasm-http-server/commits?author=EliCDavis\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/nlepage/go-wasm-http-server/issues?q=author%3AEliCDavis\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/nlepage/go-wasm-http-server/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## 📝 License\n\nCopyright © 2025 [Nicolas Lepage](https://github.com/nlepage).\u003cbr /\u003e\nThis project is [Apache 2.0](https://github.com/nlepage/go-wasm-http-server/blob/master/LICENSE) licensed.\n\n***\n_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnlepage%2Fgo-wasm-http-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnlepage%2Fgo-wasm-http-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnlepage%2Fgo-wasm-http-server/lists"}