Wails v2: route /api requests before matching embedded assets (worked example)

[felixgrov]

Prepared Q&A example: this question is being posted together with its solution, so it does not need a maintainer to investigate an unresolved application bug.

In Wails v2, suppose the asset filesystem contains a file at api/health, and the application also provides an HTTP API at /api/health.

With both Assets and Handler configured in assetserver.Options, a GET for that path can be satisfied by the static asset before the custom handler runs.

How should /api/ routes take precedence while other requests still use Wails' normal asset handling? Should this routing live in Handler or Middleware?

[hexvalid]

Use assetserver.Options.Middleware to dispatch the API prefix before calling Wails' default handler.

Handler is a fallback for GET requests that are absent from Assets; a matching static file therefore wins. Middleware receives the default handler as next and can decide whether to call it.

For example, with assets as your existing filesystem:

api := http.NewServeMux()
api.HandleFunc("/api/health", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    _, _ = w.Write([]byte("{\"ok\":true}"))
})

assetOptions := &assetserver.Options{
    Assets: assets,
    Middleware: func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            if strings.HasPrefix(r.URL.Path, "/api/") {
                api.ServeHTTP(w, r)
                return
            }
            next.ServeHTTP(w, r)
        })
    },
}

Assign assetOptions to options.App.AssetServer. Imports for this snippet are net/http, strings, and github.com/wailsapp/wails/v2/pkg/options/assetserver.

The prefix check reserves all /api/ paths for the API, including its 404 responses; it deliberately does not match the bare path /api. Other paths retain the default handler.

Checked with the v2.15.0 options type and a Go httptest harness: an existing api/health asset is overridden, a normal CSS asset still works, and an unknown API path returns 404. This checks the HTTP routing; it is not a native webview smoke test.

References: AssetServer options, Options source.

This is the companion solution to the prepared example above.