README
¶
livereload
livereload is a small Go helper for development-time live reloading. It exposes a WebSocket endpoint and provides a browser snippet that reconnects after a server restart and refreshes the page automatically.
Installation
go get github.com/kodehat/livereload
Requirements
- Go 1.26+
- A
net/httpserver
Usage
Register the WebSocket endpoint:
Only register the route and inject the script when your app is running in a development mode.
package main
import (
"fmt"
"net/http"
"time"
"github.com/kodehat/livereload"
)
func main() {
mux := http.NewServeMux()
params := livereload.NewParams()
mux.HandleFunc(params.ReloadPath, livereload.Handler(params))
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write([]byte(`
<!doctype html>
<html>
<head>
<title>Example</title>
</head>
<body>
<h1>Hello</h1>
` + string(livereload.Script(params)) + `
</body>
</html>`))
})
http.ListenAndServe(":8080", mux)
}
If your app is mounted under a sub-path, build params with options:
params := livereload.NewParams(
livereload.WithContextPath("/myapp"),
livereload.WithReloadPath("/events"),
livereload.WithPingInterval(5*time.Second),
livereload.WithMaxReconnects(10),
livereload.WithReconnectDelay(2*time.Second),
)
fmt.Fprint(w, livereload.Script(params))
API
Params
Params stores the app ContextPath, websocket ReloadPath, and reconnect timing.
NewParams(opts ...Option) Params
Creates a Params value with these defaults:
ContextPath:""(root-mounted app)ReloadPath:"/reload"PingInterval:2sMaxReconnects:5ReconnectDelay:1s
Use WithContextPath, WithReloadPath, WithPingInterval, WithMaxReconnects, and WithReconnectDelay to override specific values.
Option
Functional option used by NewParams.
WithContextPath, WithReloadPath, WithPingInterval, WithMaxReconnects, WithReconnectDelay
Helpers for customizing Params when constructing it with NewParams.
Handler(params Params) http.HandlerFunc
Returns a handler for the websocket endpoint. params.PingInterval controls how often the connection is pinged.
Script(params Params) template.HTML
Returns the JavaScript snippet to inject into HTML pages. params.ContextPath is the app base path, params.ReloadPath overrides the websocket endpoint path, and params.MaxReconnects plus params.ReconnectDelay control the reconnect loop.
How it works
- The browser opens a WebSocket connection to
contextPath + reloadPath. - While the server is running, the connection stays alive.
- When the server restarts, the socket closes.
- The script retries the connection.
- Once the connection is restored, the page reloads automatically.
Notes
- The snippet is intended for development use.
- Keep both the route and the script out of production builds.
- Inject it into your HTML before
</body>or in<head>.
Documentation
¶
Overview ¶
Package livereload provides a WebSocket-based live-reload handler and a JavaScript snippet for use during development. When the server restarts, the WebSocket connection drops; the browser-side snippet detects the close, reconnects, and calls location.reload() once the server is back up.
Usage:
// Register the WebSocket endpoint params := livereload.NewParams() mux.HandleFunc(params.ReloadPath, livereload.Handler(params)) // Inject the JS snippet into every HTML page (before </body> or in <head>) fmt.Fprint(w, livereload.Script(params))
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(params Params) http.HandlerFunc
Handler returns an http.HandlerFunc that upgrades the connection to a WebSocket and keeps it alive with periodic pings. Params.PingInterval controls the ping cadence. When the server shuts down or restarts, the connection is closed with StatusGoingAway, causing the browser-side script to detect the disconnect and trigger a reload.
func Script ¶
Script returns the JavaScript snippet that should be injected into every HTML page during development. It opens a WebSocket to params.ContextPath+ params.ReloadPath, uses Params.MaxReconnects and Params.ReconnectDelay for reconnect behavior, and calls location.reload() when the server comes back after a restart.
The returned value is html/template.HTML so it can be used safely with Go's html/template package without additional escaping.
Types ¶
type Option ¶
type Option func(*Params)
Option configures Params values for NewParams.
func WithContextPath ¶
WithContextPath sets the app mount path.
func WithMaxReconnects ¶
WithMaxReconnects sets the browser reconnect limit.
func WithPingInterval ¶
WithPingInterval sets the websocket ping interval.
func WithReconnectDelay ¶
WithReconnectDelay sets the reconnect delay used by the browser script.
func WithReloadPath ¶
WithReloadPath sets the websocket endpoint path.
type Params ¶
type Params struct {
// ContextPath is the path where the app is mounted.
ContextPath string
// ReloadPath is the websocket endpoint path. Empty uses /reload.
ReloadPath string
// PingInterval controls how often the server pings the websocket. Zero
// uses the default 2s interval.
PingInterval time.Duration
// MaxReconnects limits how many reconnect attempts the browser makes. Zero
// uses the default of 5.
MaxReconnects int
// ReconnectDelay controls the base delay between reconnect attempts. Zero
// uses the default of 1s.
ReconnectDelay time.Duration
}
Params configures the app context path, websocket reload path, and timing settings used by the reconnect loop. Use NewParams to construct a Params value with defaults and functional options.
Source Files