webx

README

webx

Beautiful, accessible UI components built with Go, Templ, Tailwind CSS, DaisyUI, and Datastar.

Philosophy

webx is inspired by daisyui. Like daisyui, this is a component library you install as a dependency. Fork it and own it.

• You own the code. Need to change something? Just edit it.
• No versioning conflicts or breaking changes to worry about.
• Zero configuration complexity. Customize by changing the code.
• Server-side rendering with Go/templ — no Node.js build step for components.
• ~15KB of JavaScript total (the Datastar library) for all frontend interactivity.

Component structure

Each component lives in its own directory under ui/ and follows a consistent pattern:

ui/button/
  button.templ       # Component template (Props struct, variants, rendering)
  button_templ.go    # Generated Go code (do not edit)

Interactive components that need a server-side handler add extra files:

ui/form/
  form.templ         # Component template
  form_templ.go      # Generated Go code
  handler.go         # SSE handler for Datastar interactivity

Components use DaisyUI classes for styling and Datastar attributes for interactivity:

package button

type Props struct {
    ID         string
    Class      string
    Attributes templ.Attributes
    Variant    Variant           // btn-primary, btn-secondary, etc.
    Size       Size              // btn-lg, btn-sm, btn-xs
    Disabled   bool
    OnClick    string            // Datastar action expression
}

templ Button(props ...Props) {
    // Optional variadic props — sensible zero-value defaults
    // DaisyUI classes merged with utils.TwMerge()
    // Datastar attributes spread via ds.* helpers
}

Import and use in your templ files:

import "github.com/plaenen/webx/ui/button"

@button.Button(button.Props{Variant: button.VariantPrimary}) {
    Click me
}

Prerequisites

• Go 1.24+

Getting started

# Install dependencies (downloads DaisyUI, Datastar, tidies modules)
go tool task install:all

# Generate templ + build Tailwind
go tool templ generate
go tool gotailwind

# Run the showcase (uses open-source Datastar)
go run ./cmd/showcase serve

The showcase starts at http://localhost:3000.

Datastar Pro (optional)

The showcase supports both open-source Datastar and Datastar Pro. Open-source is the default and requires no license.

To use Datastar Pro, purchase a license from data-star.dev and place the files in the byol/ directory (gitignored):

byol/
  datastar/
    datastar-pro.js
    datastar-inspector.js
    datastar-pro-rocket.js    # optional

Then start the showcase with the --pro flag:

go run ./cmd/showcase serve --pro

Pro mode enables the Datastar inspector and loads from your local BYOL files.

Documentation

Overview

Provides context for webx templates

Index

• Variables
• func Middleware(cfg MiddlewareConfig) func(http.Handler) http.Handler
• func Post(url string) string
• func SecurityHeadersMiddleware(secure ...bool) func(http.Handler) http.Handler
• type Context
  • func FromContext(ctx context.Context) *Context
  • func NewContext() *Context
  • func (c *Context) APIPath(path string) string
  • func (ctx *Context) WatchScope(scope string, baseKey string) string
  • func (c *Context) WithContext(ctx context.Context) context.Context
• type MiddlewareConfig
• type Watcher

Variables

var Static embed.FS

Functions

func Middleware

func Middleware(cfg MiddlewareConfig) func(http.Handler) http.Handler

Middleware reads or creates session/CSRF/theme cookies and populates Context on each request. On mutating methods it validates the signed double-submit CSRF token.

func Post

func Post(url string) string

Post returns a Datastar expression that performs a POST request to the given URL.

func SecurityHeadersMiddleware

func SecurityHeadersMiddleware(secure ...bool) func(http.Handler) http.Handler

SecurityHeadersMiddleware sets common security response headers. When secure is true (i.e. HTTPS / production), HSTS is also added.

Types

type Context

type Context struct {
	SessionID string
	CSRFToken string
	Theme     string
	BasePath  string    // prefix for all SSE handler routes (e.g. "/showcase")
	StreamURL string    // URL for the reactive SSE stream endpoint (e.g. "/showcase/stream")
	Watchers  []Watcher // reactive scope watchers accumulated during render
	// contains filtered or unexported fields
}

Context carries request-scoped state through the middleware chain and into templ components. Retrieve it with FromContext.

func FromContext

func FromContext(ctx context.Context) *Context

FromContext extracts the webx Context from a context.Context. If none is present, a new empty Context is returned.

func NewContext

func NewContext() *Context

NewContext returns an empty Context.

func (*Context) APIPath

func (c *Context) APIPath(path string) string

APIPath returns the full path for a component SSE handler by prepending the BasePath. For example, with BasePath "/showcase" and path "/calendar/navigate", it returns "/showcase/calendar/navigate".

func (*Context) WatchScope

func (ctx *Context) WatchScope(scope string, baseKey string) string

WatchScope registers a scope watcher and returns its unique signal key. Multiple components can watch the same scope — each gets a distinct key so their data-effects don't interfere with each other.

func (*Context) WithContext

func (c *Context) WithContext(ctx context.Context) context.Context

WithContext stores the webx Context into a context.Context.

type MiddlewareConfig

type MiddlewareConfig struct {
	Secret []byte // HMAC-SHA256 key, minimum 32 bytes — panics if shorter
	Secure bool   // Secure flag on cookies (true for HTTPS / production)
}

MiddlewareConfig configures the webx middleware.

type Watcher

type Watcher struct {
	Scope string // e.g. "customers:*"
	Key   string // unique signal key, e.g. "customers_WILD", "customers_WILD_2"
}

Watcher pairs a scope with a unique signal key for that watcher. Multiple components can watch the same scope, each with its own key.