webassets

README

webassets

A fast, flexible Go package for serving static web assets with in-memory caching, on-the-fly minification, and virtual bundle support.

Features

• In-memory caching: Serve assets from memory for maximum performance.
• On-the-fly minification: Minify JavaScript and CSS using tdewolff/minify.
• Virtual bundles: Concatenate and serve multiple files as a single asset (e.g., app.bundle.js).
• Singleflight protection: Prevents duplicate work under concurrent load.
• Customizable error logging: Plug in your own logger for visibility into handled errors.
• Cache exclusion: Exclude specific URL prefixes from caching.
• Secure by default: Files prefixed with _ are not served.

Installation

go get github.com/yourusername/webassets

Usage

import (
    "net/http"
    "github.com/yourusername/webassets"
)

func main() {
    h := webassets.New("./web/static",
        webassets.WithCache(true),
        webassets.WithMinification(true),
        webassets.WithBundle("app.bundle.js", "js/vendor.js", "js/app.js"),
        webassets.WithErrorLogger(func(err error) { log.Println("webassets error:", err) }),
    )
    http.Handle("/assets/", http.StripPrefix("/assets", h))
    http.ListenAndServe(":8080", nil)
}

Options

• WithCache(enabled bool): Enable or disable in-memory caching.
• WithCacheExclude(prefixes ...string): Exclude URL prefixes from caching.
• WithMinification(enabled bool): Enable or disable JS/CSS minification.
• WithBundle(name string, files ...string): Register a virtual bundle.
• WithErrorLogger(fn func(error)): Set a custom error logger.

Bundles

Bundles are virtual files that concatenate multiple source files. Example:

webassets.WithBundle("app.bundle.js", "js/vendor.js", "js/app.js")

Requesting /assets/app.bundle.js will serve the concatenated and minified result.

Security

• Files prefixed with _ (e.g., _secret.js) are not served.
• Only text-based files are minified and (future) compressed.

Roadmap

• Transparent gzip/brotli compression with content negotiation
• ETag/Last-Modified support for bundles
• Live reload/dev mode helpers

License

MIT

Documentation

Index

• type Handler
  • func New(dir string, opts ...Option) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Option
  • func WithBundle(name string, files ...string) Option
  • func WithCache(enabled bool) Option
  • func WithCacheExclude(prefixes ...string) Option
  • func WithErrorLogger(fn func(error)) Option
  • func WithMinification(enabled bool) Option

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler serves static web assets from a directory. It supports in-memory caching, on-the-fly JS/CSS minification, and virtual bundles that concatenate multiple source files.

Usage:

h := webassets.New("./web/static",
    webassets.WithCache(),
    webassets.WithMinification(),
    webassets.WithBundle("app.bundle.js", "js/vendor.js", "js/app.js"),
)
mux.Handle("/assets/", http.StripPrefix("/assets", h))

func New

func New(dir string, opts ...Option) *Handler

New creates a Handler that serves files from dir.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type Option

type Option func(*Handler)

Option configures a Handler.

func WithBundle

func WithBundle(name string, files ...string) Option

WithBundle registers a virtual bundle file accessible at /<name>. When requested, the source files are read from the handler root directory, concatenated in order, and optionally minified.

func WithCache

func WithCache(enabled bool) Option

WithCache enables in-memory caching. Each asset is read from disk on the first request and served from memory on all subsequent requests.

func WithCacheExclude

func WithCacheExclude(prefixes ...string) Option

WithCacheExclude prevents paths with the given URL prefixes from being cached. Only applies when WithCache is also used.

func WithErrorLogger

func WithErrorLogger(fn func(error)) Option

WithErrorLogger sets a function that is called whenever an error is handled gracefully (e.g. a missing file, a failed minification). The handler always recovers and returns a safe HTTP response; this just gives you visibility. Example: webassets.WithErrorLogger(func(err error) { slog.Error(err.Error()) })

func WithMinification

func WithMinification(enabled bool) Option

WithMinification enables on-the-fly minification of JavaScript and CSS. Minification errors are silently ignored and the original content is served.