diff --git a/README.md b/README.md index 3d5d4bf..a030c33 100644 --- a/README.md +++ b/README.md @@ -15,21 +15,122 @@ ✨ [Demos](https://nlepage.github.io/go-wasm-http-server/) -## Install +## Requirements -TODO +`go-wasm-http-server` requires you to build your Go application to WebAssembly, so you need to make sure your code is compatible: +- no C bindings +- no System dependencies such as file system or network (database server for example) ## Usage -TODO +### Step 1: Build to `js/wasm` + +In 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): + +📄 `server.go` +```go +// +build !js,!wasm + +package main + +import ( + "net/http" +) + +func main() { + // Define handlers... + + http.ListenAndServe(":8080", nil) +} +``` + +becomes: + +📄 `server_js_wasm.go` +```go +// +build js,wasm + +package main + +import ( + wasmhttp "github.com/nlepage/go-wasm-http-server" +) + +func main() { + // Define handlers... + + wasmhttp.Serve(nil) +} +``` + +You 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. + +Then build your WebAssembly binary: + +```sh +GOOS=js GOARCH=wasm go build -o server.wasm . +``` + +### Step 2: Create ServiceWorker file + +Create a ServiceWorker file with the following code: + +📄 `sw.js` +```js +importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v1.0.0/sw.js') + +registerWasmHTTPListener('path/to/server.wasm') +``` + +By default the server will deploy at the ServiceWorker's scope root, check [`registerWasmHTTPListener()`'s API](https://github.com/nlepage/go-wasm-http-server#registerwasmhttplistener) for more information. + +You may want to add these additional event listeners in your ServiceWorker: + +```js +// Skip installed stage and jump to activating stage +addEventListener('install', (event) => { + event.waitUntil(skipWaiting()) +}) + +// Start controlling clients as soon as the SW is activated +addEventListener('activate', event => { + event.waitUntil(clients.claim()) +}) +``` + +### Step 3: Register the ServiceWorker + +In your web page(s), register the ServiceWorker: + +```html + +``` + +Now your web page(s) may start fetching from the server: + +```js +// The server will receive a request for "/path/to/resource" +fetch('server/path/to/resource').then(res => { + // use response... +}) +``` + +## API + +FIXME ## Why? -TODO +`go-wasm-http-server` can help you put up a demonstration for a project without actually running a Go HTTP server. ## How? -TODO +If you want to know how `go-wasm-http-server` works, I will be presenting the project at [the FOSDEM 2021 Go devroom](https://fosdem.org/2021/schedule/room/dgo/). + +The slides are available [here](https://nlepage.github.io/go-wasm-http-talk/). ## Author diff --git a/docs/hello-state/sw.js b/docs/hello-state/sw.js index 38d585e..686056e 100644 --- a/docs/hello-state/sw.js +++ b/docs/hello-state/sw.js @@ -1,4 +1,4 @@ -importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@078ff3547ebe2abfbee1fd5af9ca5ad64be480c0/sw.js') +importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v1.0.0/sw.js') addEventListener('install', (event) => { event.waitUntil(skipWaiting()) diff --git a/docs/hello/sw.js b/docs/hello/sw.js index 38d585e..999a0e2 100644 --- a/docs/hello/sw.js +++ b/docs/hello/sw.js @@ -1,9 +1,9 @@ -importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@078ff3547ebe2abfbee1fd5af9ca5ad64be480c0/sw.js') +importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v1.0.0/sw.js') addEventListener('install', (event) => { event.waitUntil(skipWaiting()) }) - + addEventListener('activate', event => { event.waitUntil(clients.claim()) })