browser

pkg/browser is a small Go package that opens files, io.Reader contents, or URLs in the user’s default web browser. It exposes three functions — OpenFile, OpenReader, and OpenURL — that hide the platform-specific mechanics of invoking a browser, whether that’s macOS’s open, Windows’ ShellExecute syscall, or Linux’s xdg-open/x-www-browser/www-browser fallback chain.

Rather than shipping opinions about which browser to launch, it defers entirely to the client machine’s default handler, making it a thin, dependable primitive for Go CLIs and tools that need to hand off to a browser — for example opening a generated HTML report, a local dev server, or an OAuth login page.

What You Get

• OpenURL - opens a new browser window pointed at any URL using the OS’s native handler.
• OpenFile - resolves a local file path to an absolute file:// URL and opens it in the browser.
• OpenReader - writes the contents of any io.Reader to a temporary HTML file and opens it, useful for rendering generated content on the fly without managing a temp file yourself.
• Cross-platform dispatch - platform-specific build files (browser_darwin.go, browser_linux.go, browser_windows.go, browser_freebsd.go, browser_netbsd.go, browser_openbsd.go, browser_unsupported.go) select the right open mechanism at compile time via Go build tags.

Common Use Cases

• CLI tools that open a login page - a command-line OAuth flow that needs to hand the user off to a browser for authentication.
• Local dev servers - a Go program that starts a local web server and immediately opens it in the browser for the developer.
• Rendering generated reports - a build or test tool that produces an HTML report and opens it directly via OpenReader without writing to a permanent file.
• Documentation generators - godoc-style tools that open freshly generated docs in the browser.

Under The Hood

Architecture

The package is a single flat browser package built around three exported entry points in browser.go — OpenURL, OpenFile, and OpenReader — all funneling into an unexported openBrowser(url string) error. That function has no single implementation; instead, seven OS-specific files (browser_darwin.go, browser_linux.go, browser_windows.go, browser_freebsd.go, browser_netbsd.go, browser_openbsd.go, and a browser_unsupported.go catch-all guarded by a !linux,!windows,!darwin,!openbsd,!freebsd,!netbsd build constraint) each supply their own openBrowser, and the Go compiler picks exactly one at build time. This is a clean, idiomatic use of Go’s build-tag mechanism to express a strategy pattern without runtime branching or an interface — swapping or extending platform support means adding one small file, and nothing else in the package would need to change.

Tech Stack

The module targets Go 1.14 and declares a single external dependency, golang.org/x/sys v0.1.0, used only by the Windows build to call windows.ShellExecute. There is no build tooling beyond go build/go test; CI is one GitHub Actions workflow (push.yml) that runs go test -v ./... on Go 1.15 against ubuntu-latest only, meaning the darwin and windows code paths are never exercised in CI. The package has no runtime dependencies beyond the Go standard library on non-Windows platforms.

Code Quality

Testing consists solely of example_test.go, which defines three Example* functions (ExampleOpenFile, ExampleOpenReader, ExampleOpenURL) that call each public function but include no // Output: comment, so go test runs them without asserting anything — there is effectively no verified test coverage, including no coverage of the Linux fallback chain or the unsupported-OS error path. Error handling is idiomatic Go: every public function returns an error, and OpenReader wraps failures with fmt.Errorf and descriptive context. Naming is minimal and consistent (openBrowser, runCmd). No linter configuration or CI lint step is present.

What Makes It Unique

The package is not novel — it’s a straightforward wrapper around OS-native “open a URL” invocations, comparable to Python’s webbrowser module or Node’s open package. Its two distinguishing touches are the ordered fallback chain of three Linux openers (xdg-open, x-www-browser, www-browser) and the OpenReader convenience, which removes the boilerplate of writing a reader’s contents to a temp file before opening it.