web

README

web

A web framework for Vuka: routes, views, services and controllers are declared with decorators, parameters bind by name, and web.New() gathers everything into an app.

package main

import (
	"github.com/vuka-lang/ui"
	"github.com/vuka-lang/web"
)

@web.Service
type PetStore struct{ db *DB }            // built from its fields, a lazy singleton

@web.Get("/pets")
@web.Template("views/pets.templ")         // a templ component renders the result
func ListPets(store *PetStore) Result[PetList] { … }

@web.Get("/pets/{id}")
@web.Template("views/pet.html")           // html/template, the result as data
func ShowPet(id int, store *PetStore) Result[Pet] { return store.Find(id) }

@web.Get("/")
func Home(r *http.Request) ui.Node {    // JSX
	return <Layout title="Home"><h1>Hi</h1></Layout>
}

@web.Post("/api/pets")
func CreatePet(in NewPet, store *PetStore) Result[Pet] { … }   // JSON in, JSON out

@web.Controller("/admin/pets")
type PetAdmin struct{ store *PetStore }

@web.Get("/")
func (a *PetAdmin) Index() Result[[]Pet] { return a.store.All() }

func main() {
	app := web.New()       // every route, service and controller declared at init
	app.Provide(OpenDB)    // more constructors, fx-style
	app.Run(":8080")       // graceful shutdown on SIGINT/SIGTERM
}

A complete app is in examples/pets; live components in examples/live.

go get github.com/vuka-lang/web

Declaring

@web.Get(path), Post, Put, Patch, Delete, Handle(method, path)	a route; works on functions and controller methods
@web.Template(file [, name])	render the result with a view (below); before or after the route decorator
@web.Use(mw…)	HTTP middleware for this route, func(http.Handler) http.Handler
@web.Service	a struct becomes a dependency
@web.Controller(prefix)	a struct becomes a dependency whose route methods are served under prefix
@web.Live(path, opts…)	a stateful component becomes a live page (below)

Paths use {name} for a segment and {name...} for the rest of the path, and match exactly (/pets doesn't match /pets/). Under a controller, "/" is the prefix itself.

Route decorators are Vuka declarers (func(*vuka.Decl)): they run once at init and record the function with its parameter names. Other decorators on the same function still wrap it — @audited below runs on every call.

The app

web.New(opts…) takes a snapshot of what has been declared, so several apps (in tests, say) each get their own container and singletons.

Option
web.Provide(ctors…)	constructors for the container (also app.Provide)
web.Eager(ctors…)	constructors built and started even when nothing needs them (also app.Eager)
web.OnStart(fn), web.OnStop(fn)	lifecycle hooks (also app.OnStart/app.OnStop; below)
web.Check(fn)	a check Build runs with its own (also app.Check)
web.Options(opts…), web.OptionFunc(f)	several options as one; an option written as code (below)
web.Use(mw…)	app-wide middleware (also app.Use); runs for every request, 404s included
web.WithRouter(r)	another router (below)
web.Only(pkgs…)	take only the declarations of these packages (import paths; "main")
web.Dev()	show internal error messages; also VUKA_ENV=development
web.DotEnv(files…), web.NoDotEnv(), web.Require(keys…)	env files and required variables (below)
web.OnError(f)	replace the error page / JSON error body
web.LiveLayout(f), LiveKey(k), LiveOrigins(p…), LiveTokenTTL(d), WithRelay(r)	live pages (below)
web.NoTailwind(), web.Tailwind(path)	no stylesheet; or the project's Tailwind stylesheet at another path (below)
web.NoToolbar()	no development toolbar (below)

app.Build() resolves everything — every parameter of every route, every result and view, the whole dependency graph — and returns all problems at once, each naming the route, its source position and the parameter:

web: GET /pets (main.ListPets at pages.vuka:24): component PetsPage: main.PetList has no field for parameter title
web: GET /admin (main.Admin at admin.vuka:9): parameter db *sql.DB: no provider for *sql.DB, needed by main.Admin at admin.vuka:9
web: dependency cycle: *main.A -> *main.B -> *main.A

Options from libraries

A library hands the app one option that does all it needs: web.Options groups options, and web.OptionFunc runs code against the app inside New, before Build, where every App method is open to it.

func Cache(cfg Config) web.Option {
	return web.Options(
		web.Provide(cfg, NewCache),
		web.OptionFunc(func(a *web.App) {
			a.Use(cacheHeaders)
			a.Get("/cache/stats", (*Cache).Stats)
			a.OnStop(func(ctx context.Context) error { return flush(ctx) })
		}),
		web.Check(func(*web.App) error { return cfg.Validate() }),
	)
}

app := web.New(Cache(cfg), web.Dev())

A check's error is one of Build's, reported with the routes' and the container's.

app.Handler() (an http.Handler to mount anywhere; it panics when Build fails), app.Start(ctx) and app.Run(addr) call Build first, so nothing is served from a broken app. Register everything before the first of them. app.Run("") listens on :$PORT, else :8080. web.Resolve[T](app) returns a dependency, for tests and main.

.env files

web.New() first reads env files into the process environment, so every constructor, Start method and option sees their values through os.Getenv or web.Env. By VUKA_ENV, the first file listed winning:

VUKA_ENV	files
development, staging, …	.env.<env>.local, .env.local, .env.<env>, .env
test (also when unset under go test)	.env.test, .env
unset	.env.local, .env

The real environment wins over every file: a key is set only when the process doesn't have it yet. .env.local files hold one machine's settings and are skipped in tests, so test runs don't depend on the developer's box. VUKA_ENV picks the files, so it comes from the real environment; set in a file, it still turns on web.Dev() behaviour.

Files are read from the working directory or, when it has none of them, from the nearest parent up to the module root (the directory with go.mod), so go test ./pkg/... finds the project's .env. Missing files are fine. web.DotEnv("a.env", "b.env") replaces the list (first wins), web.NoDotEnv() reads none, and web.LoadEnv(files…) loads them earlier — for options built from the environment; New reading the same files afterwards changes nothing. With VUKA_ENV=development the app logs which files it read.

Syntax:

# a comment
PORT=8080
export HOST=localhost              # export is allowed; " #" starts a comment
NAME=two words                     # unquoted values are trimmed
RAW='no $expansion, no \n escapes'  # single quotes (and `backticks`) are literal
KEY="-----BEGIN KEY-----
multi-line, with \n \t \" \\ and \$ escapes"
DATABASE_URL=postgres://${HOST}:5432/app
REPLICA_URL="${REPLICA_HOST:-$HOST}"   # :- gives a default for unset or empty
app.name=pets                      # keys: [A-Za-z_][A-Za-z0-9_.]*

$VAR and ${VAR} expand in unquoted and double-quoted values from the real environment, then the keys defined above (in this file or a lower-precedence one); an undefined variable is empty. A malformed line is a Build error with the file and line; nothing of that file is set.

Reading:

port := web.Env("PORT", 8080)                   // int; the default when unset or empty
debug := web.Env[bool]("DEBUG")                 // true/false, 1/0, yes/no, on/off
ttl := web.Env("CACHE_TTL", 5*time.Minute)      // time.Duration
hosts := web.Env[[]string]("ALLOWED_HOSTS")     // comma-separated (any slice of these)
db := web.Env[*url.URL]("DATABASE_URL")         // absolute URLs; also encoding.TextUnmarshaler types
key := web.MustEnv[string]("SECRET_KEY")        // panics when unset or invalid

app := web.New(web.Require("DATABASE_URL", "SECRET_KEY"))

A value that doesn't convert gives the default, and the next app.Build() (or app.Start, for constructors) fails naming the variable. web.Require fails Build listing every missing variable, the files looked for and the keys of .env.example that are unset too:

web: missing environment variables: SECRET_KEY (read .env; looked for .env.local, .env); also unset, listed in .env.example: SMTP_HOST

Errors and logs name variables and files, never values. Keep .env and .env*.local out of git (this repository's .gitignore does) and commit an .env.example with the keys and harmless values instead; in production, set real environment variables.

Parameters

Each parameter binds by its type and name:

parameter	from
*http.Request, http.ResponseWriter, context.Context	the request (the context is the request's)
a provided type	the container
a scalar: string, ints, floats, bool, a encoding.TextUnmarshaler; *T of one (nil when absent), []T (repeated)	the path segment of the same name, else the query parameter ?name=; absent → zero value
one struct, or pointer to a struct that isn't provided (with exported fields; else it is a missing dependency)	the body: JSON for application/json, else the form (urlencoded, multipart) or query; then path segments into fields of the same name

Struct fields bind by their form tag, else json tag, else name, matched case-insensitively; validate:"required" rejects a zero value. A malformed value answers 400 with a message (id: "x" is not an integer).

A call decorator reaches the request through the handler's context.Context argument: web.Request(c.Context()), web.ResponseWriter(c.Context()).

decorator audited(c) {
	r := web.Request(c.Context())
	c.Next()
	log.Println(r.Method, r.URL.Path, c.Err())
}

@web.Delete("/{id}")
@web.Use(requireToken)
@audited
func (a *PetAdmin) Remove(ctx context.Context, id int) error { … }

Results

A handler returns nothing, error, T, (T, error) or Result[T].

result	response
nothing, a nil error	204 — unless the handler wrote the response itself through its http.ResponseWriter
ui.Node (JSX, templ)	HTML
T with @web.Template	the view, HTML
T without	JSON, 200
web.Redirect(url) (as a value or an error)	302 for GET/HEAD, else 303
*web.Error, wrapped or not	its status and message
any other error	500; its message only in dev

Errors are an HTML page on HTML routes (a view, a ui.Node or a redirect result) and {"error": …, "status": …} elsewhere. web.NotFound, Unauthorized, Forbidden, Conflict, web.BadRequest(msg), web.Status(code, format, args…); errors.Is(err, web.NotFound) matches by status. web.Redirect is also a ui.Node, so a page handler can return it. Panics answer 500. A handler that wrote the response and then returns an error can't change it any more: the error is logged.

Views

templ. @web.Template("views/pets.templ") uses the file's one exported component; with several, name one: @web.Template("cards.templ", "Card"). The result fills the component's parameters: whole, when it has one parameter the result is assignable to; otherwise the result is a struct (or pointer to one) and each parameter takes the field of its name (exactly, or with the first letter's case changed: title ↔ Title). Layouts are templ's own composition (@Layout(title) { … }).

templ PetsPage(title string, pets []Pet) { @Layout(title) { … } }

type PetList struct { Title string; Pets []Pet }

html/template. Any other file is parsed once at Build and executed with the result; a second argument names a {{define}}d template to execute.

JSX / render functions. Return a ui.Node; no view needed.

Views are embedded at compile time (vuka.File), so the binary carries them, from the handler's package directory or below it. A .templ file beside the handler is part of its package; one in a subfolder is that folder's package, as Go has it — views/pets.templ starts with package views — and Vuka compiles it and imports it for you:

examples/pets/
  pages.vuka        @web.Template("views/pets.templ"), @web.Template("views/pet.html")
  model/pet.go      package model: Pet, shared by handlers and views
  views/layout.templ  package views: Layout
  views/pets.templ    package views: PetsPage, composed with @Layout
  views/pet.html

Only the subfolder's exported components can be views, and its types can't come from the handler's package (package main can't be imported): put shared types in a package of their own, like model here. A JSX page uses a subfolder's component through its import, <views.Layout title="Home">.

Live components

A stateful component (a struct embedding ui.Live) keeps its state on the server and answers its elements' events over a WebSocket; the page changes in place.

@web.Live("/counter")
type Counter struct {
	ui.Live
	Start int // ?start=3
	n     int
}

func (c *Counter) Mount() { c.n = c.Start }
func (c *Counter) Inc()   { c.n++ }

func (c *Counter) Render() ui.Node {
	return <div><output>{c.n}</output><button onClick={c.Inc}>+</button></div>
}

How a page becomes live. Two ways, one mechanism:

• @web.Live(path) on a stateful component serves it as a GET page. Its exported fields of provided types are injected; the others that hold text bind from the path segment or query parameter of their name (form tag, else the field name, ignoring case). The page is the component inside the layout web.Layout(f) names, else the app's web.LiveLayout(f), else a bare document — f is func(page ui.Node) ui.Node. web.Use(mw…) adds middleware. From Go: app.Live("/counter", &Counter{Start: 1}) (the value's fields are the defaults).

• Any GET route whose page — a ui.Node result, or a templ view — renders a stateful component or an event handler is live by itself:

  @web.Get("/")
  func Home() ui.Node { return <Shell title="Home"><Counter Start={10} /></Shell> }
  

  A Vuka component rendered from a templ view is live too: templ passes the context on. html/template views and JSON are never live.

The first, HTTP render is complete HTML, and before </body> goes <script src="/_vuka/live.js" data-vk-token="…" defer>. The script opens /_vuka/live?t=<token> and sends join; the server runs the same route again — a GET to the URI in the token, with the WebSocket request's headers (cookies, auth), through the app's and the route's middleware, with its dependencies — and the page it renders becomes the connection's live.Session. That second run mounts the instances that keep state (LiveView's two-phase mount). A join the route answers with a redirect sends redirect (the browser follows it); any other non-page answer (a 404, JSON) is an error, and the connection closes.

The route's handler runs once per connection: its result is the page, and the page is rendered again after every event. State belongs in the components.

Events. onClick={c.Inc} renders data-vk-on-click="c1:0"; the runtime listens on the document for each event type a page names and sends the nearest handler's id, the element's value (a checkbox's "true"/"false"), the key of a keyboard event, and a submitted form's fields. What a handler receives follows its type (Vuka's rules: nothing, the value, ui.Event, url.Values, a struct bound from the form). Two attributes tune it:

attribute
data-vk-debounce="150"	send the element's events (not submits) 150ms after the last one
data-vk-key="Enter Escape"	send a keyboard event only for these keys

Submits are preventDefaulted; so are clicks on links and on buttons of a form without a submit handler. A form whose submit handler succeeds is reset to what the server rendered; one whose handler returns an error keeps what the user typed. The element of a click or submit carries aria-busy="true" until the reply.

Patches. The reply carries the HTML of each component whose output changed (the page itself is c0). The runtime morphs the element in place: elements are matched by id, else data-vk-id, else position and tag; a focused field keeps its value and caret; another field takes the server's value when it changed. Give list rows an id for stable identity across inserts and removals. data-vk-ignore (with an id) leaves an element as the browser has it. A whole-document c0 patch morphs the <body> and sets the title.

Browser hooks. <html data-vk-state> is connecting, connected, disconnected or closed (style a banner on it). The document receives vk:patched (detail.ids) after each render or patch and vk:error (detail.message) for a handler's error or a failed message; errors are also logged to the console.

Broadcasts. web.Broadcast(ctx, topic, msg) — from an event handler, an Update, or any request — delivers msg to every component subscribed to topic (c.Subscribe(topic) in Mount), in every connected page; each takes it in the Update overload of its type and its page gets the patch. app.Broadcast(ctx, topic, msg) does the same from outside a request. Delivery is in-process; web.WithRelay(r) sends broadcasts through a Relay (Publish(ctx, topic, msg) / Subscribe(deliver)) to reach every replica.

@web.Live("/chat/{room}")
type Chat struct {
	ui.Live
	Room  string   // the path segment
	Log   *ChatLog // injected
	lines []string
}

func (c *Chat) Mount()          { c.Subscribe("chat:" + c.Room) }
func (c *Chat) Update(m Said)   { c.lines = append(c.lines, m.Who+": "+m.Text) }
func (c *Chat) Update(j Joined) { c.lines = append(c.lines, j.Who+" joined") }

func (c *Chat) Send(ctx context.Context, f ChatForm) error {
	return web.Broadcast(ctx, "chat:"+c.Room, Said{c.name, f.Text})
}

Connections. One session per connection; its events and broadcasts are handled one at a time, in order, by the connection's goroutine. The server pings every 25 seconds; a closed connection unmounts its components. app.Stop (and Run's shutdown) closes every connection as "going away". The runtime reconnects with jittered exponential backoff (up to ~10s) and joins again — the route runs again and the state starts over; what was not saved elsewhere is lost.

Security. The token is the page's URI and an expiry (LiveTokenTTL, 12h by default), HMAC-SHA256-signed with the app's key: a connection can only rebuild a page the app rendered, and it does so with the connecting browser's own cookies, through the route's own middleware. Each app draws a random key; replicas behind one hostname need a shared web.LiveKey(key). A bad or expired token closes the connection with code 4001 and the runtime reloads the page (at most once in 10 seconds) for a fresh one. WebSocket upgrades only from the page's own origin, unless web.LiveOrigins(patterns…) allows more ("*.example.com").

Navigation

A paged list, tabs kept in the URL, a list and its detail pages: moving between them shouldn't reload the document, drop the connection or lose the scroll position of the page you come back to. ui.Link is a link a live page follows over its connection:

<ui.Link href="/books/7">Dune</ui.Link>                 // navigate: another page
<ui.Link href={shelfURL(s.page + 1)} patch>Next</ui.Link> // patch: this page, other parameters

It renders <a href="…" data-vk-link> (="patch"), so it stays a plain link without JavaScript, on a page that isn't live, in a new tab (target, a modifier key, the middle button) and to another origin — the runtime leaves those clicks to the browser.

• Patch moves to another URL of the same page. The components stay mounted with their state; the route runs again for the new URL (its middleware too), so a Live page's props are bound from it again, and its Update overload taking a web.URLParams struct gets the new params first — bound the same way, from the path segment or query parameter of each field's name. Then the usual patch is sent.
• Navigate moves to another page: its route runs as a page load does (middleware, gates, dependencies, layout), its components mount on the same connection, and the old ones unmount. Under protocol v2 the page arrives as a change to the trees the connection holds: a shared layout isn't sent again.

type ShelfParams struct {
	web.URLParams
	Page int // ?page=
}

func (s *Shelf) Mount()                { s.show(s.Page) }   // the first URL
func (s *Shelf) Update(p ShelfParams)  { s.show(p.Page) }   // each patch

From a handler, c.PushPatch(href) and c.PushNavigate(href) move the page once the reply is applied; in a chain, ui.JS.Patch(href) and ui.JS.Navigate(href) do it from the browser. A URL whose route answers anything but a page — a redirect, an error, JSON, another origin — is loaded as usual, and so is any navigation while the page isn't connected, or one that fails.

In the browser: the address changes with pushState, and back and forward patch or navigate to match (patch within one page's entries); a navigation scrolls to the top or to the URL's #hash, back restores where the page was, and focus moves to the new page's [autofocus] element, else its <main>, else its first component. The page's <title> follows, and its <head> elements the document lacks (stylesheets, scripts, meta tags) are added once; scripts in the new page's body don't run. <html data-vk-navigating> is set while a navigation is in flight, and vk:navigate fires on window when one completes (detail: {url, patch}). Events aren't sent while the page is on its way out, and a new page drops the optimistic pushes still waiting for the old one, without their hooks. A reconnect joins the page the connection moved to.

JS commands

Opening a menu, showing a dialog, moving focus or copying a snippet needs no server: a chain of JS commands as an on… value runs in the browser, at once, and a Push step in it calls a handler when the server should know too.

func (c *Chores) Render() ui.Node {
	return <section>
		<button onClick={ui.JS.RemoveClass(ui.Ref("menu"), "hidden")}>Pick one</button>
		<ul ref="menu" class="menu hidden">
			{for _, ch := range c.chores {
				<li><button value={ch} onClick={ui.JS.AddClass(ui.Ref("menu"), "hidden").Push(c.Pick)}>{ch}</button></li>
			}}
		</ul>
		{for _, ch := range c.chores {
			<p>{ch} <button value={ch} onClick={ui.JS.Confirm("Delete " + ch + "?").Push(c.Delete)}>delete</button></p>
		}}
		<p ref="status">{len(c.chores)} left</p>
	</section>
}

func (c *Chores) Delete(e ui.Event) {
	// …
	c.PushJS(ui.JS.On(ui.Ref("status")).AddClass("flash")) // runs once the reply is applied
}

A chain renders as data-vk-js-<event>="[[name, args], …]" (the live protocol's "JS commands"). The runtime runs it when the event reaches the nearest element with commands or a handler for it: classes and attributes, Show/Hide/Toggle (the style attribute's display, with optional transition classes during/from/to), Transition, Focus, FocusFirst, a focus stack (PushFocus/PopFocus, for dialogs), Dispatch (a CustomEvent), Exec (the commands held in another attribute), Copy/CopyText (the element gets data-copied for 1.5s), ScrollTo, SetValue (fires input and change), and the steps that steer the chain: Key("Escape") (stop for other keys), Confirm(msg) (stop on cancel), Debounce/Throttle (the steps after them, per element and event; a debounced step waiting in a form runs before the form's submit), and If/ElseIf/Else/End over a target's checked state, value, attribute, selector match or existence. Targets: the element itself, ui.Ref(name) (the refed element of the same component instance, not of the instances inside it), ui.Closest(sel), ui.Inner(sel), or a selector. A submit's commands preventDefault it; a push also does what a handler would (links, a form's buttons). An element with both commands and a handler for one event runs the commands first, and a declined Confirm keeps the event from the server.

Pushed commands. c.PushJS(chain) in a handler, an Update or Mount rides the reply ("js":[{"id","ops"}] on render and patch, both protocol versions) and runs after it is applied, on the component's root element.

Reconciliation. What a command changed — a class, an attribute, the style display — stays across the server's patches while the server keeps rendering that attribute as it did when the command ran: an open menu stays open while the list in it updates. When the server renders a different value, the server wins and the browser's change is dropped. A running transition's classes survive a patch until it ends.

Optimistic updates. A like should count at once and a deleted row should go at once, without waiting for the server — and come back if the server refuses. The steps before a Push in a chain are its predictions: they show immediately, and the push's reply settles them.

<button
	class={likedClass(p.liked)}
	onClick={ui.JS.AddClass(ui.This, "liked").SetText(ui.Ref("likes"), fmt.Sprint(p.likes+1)).
		Push(p.Like).OnError(ui.JS.Show(ui.Ref("like-error")))}
>
	Like
</button>
<b ref="likes">{p.likes}</b>
<p ref="like-error" hidden>Couldn't save your like.</p>

• Success (a reply without an error): the predictions stay, and reconciliation goes on as for any command — wherever the server renders something else (the count with everyone else's likes), the server wins. The OnSuccess chain runs.
• Failure (the handler returned an error, an error message, no reply within the push's timeout — 10s by default — or the connection dropping before the reply): each prediction is undone, latest first, except where the server has rendered a different value since or a later command changed it. The OnError chain runs, and vk:error fires as for any error. A push made while the page isn't connected isn't sent (the runtime doesn't queue events) and fails at once.
• Push(h, ui.KeepOnError()) never undoes (the hooks still run); ui.Timeout(d) sets how long a push waits. A reply that comes after its push timed out is applied as usual, without running hooks again.

What counts: classes, attributes, the style display (Show/Hide, a hidden attribute), the text SetText sets — reconciled like an attribute: it stays while the server renders the same text — and a field's value or checked state from SetValue. Each push in a chain settles only the steps since the previous push; a push a branch skips ends its segment too. Hooks run on the element the chain ran for, or the component's root once that element is gone; a server-pushed chain's pushes work the same way. While a push waits, its element has data-vk-pending; after a failure it has data-vk-failed until its next push — hooks for CSS:

[data-vk-pending] { opacity: .6; }
[data-vk-failed] { outline: 1px solid crimson; }

Calling JavaScript. A chart to redraw, confetti on a save, a date picker to open: Call("name", args…) calls a page function with ctx — {el, event, root, target(spec)} — and the arguments, which may be reads of the page at that moment (ui.Ref("q").Value(), .Checked(), .Attr("name")). Register functions with vuka.register; the first line lets a script run before the runtime (its registrations wait in vuka.q):

<script>
  window.vuka ||= { q: [], register(name, fn) { this.q.push([name, fn]); } };
  vuka.register("confetti", (ctx, n) => fire(ctx.el, n));
</script>

Otherwise the name is a dotted path on window ("Picker.refresh", called with Picker as this), never evaluated as code. A returned promise holds the rest of the chain until it settles; false stops the chain as a declined Confirm does. An unknown function, a throw or a rejection stops the chain and fires vk:error on the element (detail: {error, fn}); when it happens among a push's predictions, that push fails without being sent — its predictions are undone and its OnError chain runs. (A chain that waits on a promise doesn't hold back a data-vk-on-… handler on the same element; put the Push in the chain.)

Without a connection. Commands need no session: a page whose only data-vk- attributes are commands gets the runtime script without a token, runs its commands, and never opens a WebSocket — a static page can have menus and dialogs. A Push on such a page does nothing (the console warns once). A page is live when it renders a stateful component, a handler, or a command that pushes to one.

Protocol versions

The runtime joins asking for protocol v2 ({"type":"join","v":2}) and follows whatever the server answers:

• v2, render trees. Each component instance arrives as a tree: its statics (the markup the JSX fixes) around its dynamics (what Go expressions render), loops as item frames keyed by key, nested instances as references. Statics travel once per connection and are referred to by id; long strings are kept by the connection too. After an event or a broadcast the server sends, for each instance whose output changed, only the dynamics that changed: a new text or attribute, loop steps (keep, skip, insert, move a keyed item, change one in place), a token patch of a long string — or the instance's plain HTML when that is smaller. The runtime applies the changes to the trees it holds, renders the changed instances' HTML from them and morphs the page with it exactly as in v1, so focus, caret, typed values, busy states and data-vk-ignore behave the same. A counter's click is ~70 bytes instead of ~250; a todo list's events ~3–4× less than v1 (the examples' browser tests log both). A reply the runtime can't apply to its trees makes it join again.
• v1, HTML. Each changed instance's whole HTML (updates), morphed in. A Vuka session that doesn't speak v2 answers a v2 join in v1, and the page works as before.

web.LiveProtocol(1) makes the app answer in v1 whatever the page asks (LiveProtocol(2), the default, uses v2 when the Vuka session speaks it). The format is Vuka's protocol v2; <html data-vk-protocol="2"> says which one a page got.

The wire, beyond Vuka's protocol

Vuka's wire protocol as is, plus:

GET /_vuka/live?t=<token>	the WebSocket; the token in the URL, so a bad one is refused before any message
GET /_vuka/live.js?v=<hash>	the runtime, immutable for its hash (ETag otherwise)
join	runs the route; a second join on the same connection starts over; its v picks the protocol (above)
redirect	sent for a join the route redirects; the connection then closes normally (1000)
navigate	runs the URL's route (X-Vuka-Live: navigate) and makes its page the session's; the patch reply carries url and token, the new page's join token; a route that doesn't answer with a page gets redirect (its Location, else the URL)
close 4001	invalid or expired token: reload
close 4004	the route isn't a live page: the error message precedes it; no retry
close 1001	the server is stopping: reconnect
request header X-Vuka-Live: join	on the route's run for a join (navigate for a navigation's)

A broadcast arriving before join is dropped (the join renders fresh).

Dependency injection

The container holds constructors — func(deps…) T or func(deps…) (T, error) — and ready values (anything that isn't a function). @web.Service and @web.Controller structs are constructed from their fields (Vuka's vuka.Type.New; tag a field inject:"-" to leave it out). Every value is a lazy singleton per app; dependencies match by exact type (provide a constructor returning the interface to inject an interface). Missing providers, cycles and duplicates are Build errors.

Lifecycle

app.Start (and Run) builds what the routes need, then runs the start sequence; app.Stop runs the stop sequence, its reverse. The sequence holds, in order:

• ready values given to Provide, and hooks added with OnStart/OnStop, in the order they were added — a ready value was given explicitly, so it starts even when nothing needs it;
• values built from constructors, in dependency order — only those something needs (a route, a live page, another value), and those provided with web.Eager.

A value implementing Start(context.Context) error is started and one implementing Stop(context.Context) error is stopped. The first failing start ends Start with its error; every stop runs, and their errors are joined.

app := web.New(
	web.Provide(cfg),                 // cfg.Start, if any, runs first
	web.OnStart(migrate),
	web.Eager(NewMailer),             // started though no route takes it
)

Router

The default router is net/http's ServeMux with Go 1.22 patterns. Any router plugs in through

type Router interface {
	http.Handler
	Handle(method, pattern string, h http.Handler)   // canonical {name} / {name...} patterns
	Param(r *http.Request, name string) string
}

with web.New(web.WithRouter(r)). A chi adapter is a dozen lines (Handle → r.Method(method, pattern, h), Param → chi.URLParam); the tests carry a tiny one.

Tailwind

Write Tailwind classes anywhere — JSX, .templ and .html views, the class names a JS command adds — and they are styled, with no setup:

@web.Get("/")
func Home() ui.Node {
	return <Layout title="Home">
		<button class="rounded bg-emerald-500 px-4 py-2 text-white"
			onClick={ui.JS.AddClass(ui.Ref("note"), "opacity-50")}>Save</button>
		<p ref="note" class="mt-2 text-sm text-gray-500">Unsaved changes</p>
	</Layout>
}

The vuka command builds the stylesheet with the Tailwind CLI (brew install tailwindcss, or npm i -D @tailwindcss/cli) from the module's .vuka, .templ, .html and .go files and those of the dependencies that ship components (github.com/vuka-lang/ui), and every full page the app serves links it: <link rel="stylesheet" href="/_vuka/app.css?v=…"> before </head>, unless the page links it already. Fragments, JSON and live updates don't.

• vuka run keeps it rebuilt (tailwindcss --watch, into .vuka/tailwind/) and the app serves it from there; open pages swap in each new build without reloading, live state kept.
• vuka build builds it once, minified, and embeds it in the binary: served as /_vuka/app.css?v=<hash>, cached for good; revalidated by ETag without the hash. vuka gen writes the file that embeds it (vuka_tailwind_gen.go in the main package) for plain go build.

Your own theme, plugins or components go in app.css or styles/app.css at the module root — any file with @import "tailwindcss"; it replaces the built-in one, which is just that line. Elsewhere, name it: web.New(web.Tailwind("assets/site.css")) (a string literal: the vuka command reads it from the source).

web.NoTailwind() turns it all off, as does VUKA_TAILWIND=off for the vuka command. Without the Tailwind CLI, vuka run says how to install it and serves pages unstyled; vuka build fails.

web.RegisterCSS(name, css) serves another stylesheet at /_vuka/<name>; the file vuka build generates registers app.css with it.

Development toolbar

Why is this page slow, which statements did it run, what did that click do? In development every full page answers on the spot: a handle on its right edge shows the request's time and statement count, and opens a drawer of panels for that request.

• Request: method, path, the route's pattern, the handler (its name, file and line), the status, the arguments the handler was called with and where each came from (path, query, body, dependency), and the request's and response's headers (cookies and credentials hidden).
• SQL: each statement in order, with its arguments, rows and time as a bar. A statement run more than once is amber; run three times or more with different arguments it is named as an N+1, one statement per row of an earlier result. A failed or refused statement is red.
• Timeline: the app's and the route's middleware, each call decorator (@timed), the handler, the render and the statements, as bars against the request's time.
• Logs: what slog's default logger wrote for the request — with its context (slog.InfoContext(ctx, …)) or from the request's goroutine. The console gets it as before.
• Live: on a live page, each message its connection carried — the join, each event (Counter.Inc (click)), navigation and broadcast — with its time, statements, reply size and what it ran. A message that failed is red, and so are failures only the browser saw (a push timing out, a dropped connection).

The list at the top holds the page and each fetch and XHR call it made since it loaded: every response of a development app carries its record's id in X-Vuka-Toolbar. Under vuka run -watch the handle follows the next build: building… 1.2s while it compiles (the last good build still answering), build failed with the compiler's output in the drawer.

It is on under vuka run, web.Dev() or VUKA_ENV=development, and off in a test binary (so tests see the pages the app serves), with web.NoToolbar(), and in any other app: no recording, no routes, no header, no hooks. The toolbar draws itself in a shadow DOM, so the page's styles and its own don't meet, light or dark as the system prefers. The page's HTML is the same but for its script tag (in <head>, beside the stylesheet's link); live updates never carry it. The app keeps its latest 100 requests in memory and serves them under /_vuka/toolbar/.

Statements. orm's ormweb feeds the SQL panel by itself. Another database layer reports its statements with web.NoteStatement(ctx, web.Statement{SQL, Args, DB, Start, Duration, Rows, Err}); app.Toolbar() says whether to bother.

Panels of your own. web.Note(ctx, panel, v) records a value for a panel from request code — a no-op outside development, so it can stay — and web.AddPanel(name, render) draws it:

func (c *Cache) Get(ctx context.Context, key string) ([]byte, bool) {
	v, ok := c.m[key]
	web.Note(ctx, "Cache", Lookup{key, ok})
	return v, ok
}

web.AddPanel("Cache", func(notes []any) ui.Node {
	return <ul>{for _, n := range notes { <li>{n.(Lookup).Key}: {n.(Lookup).Hit}</li> }}</ul>
})

A panel noted without AddPanel lists its values.

Static files

app.Static("/assets", fsys) serves an fs.FS (an embed.FS sub-tree, os.DirFS(…)).

Plain Go

Everything works from Go without decorators. Reflection can't see parameter names, so scalar parameters need web.Params; structs, request values and dependencies bind as usual.

app := web.New(web.Provide(NewStore))
app.Get("/pets/{id}", func(s *Store, id int) (Pet, error) { … }, web.Params("s", "id"))
app.Post("/pets", func(in NewPet, s *Store) (Pet, error) { … })
app.Get("/page", page, web.View(vuka.File("views/page.html")), web.Wrap(mw))

From Go, vuka.File("…") reads from disk relative to the working directory.

Testing

go test ./...                     # the package
vuka test ./...                   # also examples/ and internal/vukatest, written in Vuka

The browser tests (examples/live, TestBrowserReconnect, TestBrowserJS…) drive a headless Chrome over the DevTools protocol (internal/chrome) and skip when none is found; VUKA_CHROME names the binary. The runtime's JS commands and navigation also run in node over a small DOM (testdata/livejs/js.js, TestLiveJSCommands), skipped without node.

Limits

• One struct parameter per handler; scalars bind from the path or query only (use *http.Request for headers and cookies).
• Views live in the handler's package directory or below it (go:embed doesn't reach up); ../shared/x.templ is an error.
• A vuka.File literal is embedded only where a decorator or attribute takes one, so there is no web.Layout(file) option; compose layouts in templ, or {{define}} them in one html file.
• Dependencies match by exact type; no named values or groups.
• Status codes for success are fixed (200/204); write through http.ResponseWriter for anything else.
• Live patches are whole components' HTML, morphed in the browser (Vuka's phase 1); a live connection's state starts over when it reconnects, and events sent while disconnected are dropped. The live endpoints are at /_vuka/… from the root: an app mounted under a path prefix needs them routed there.
• Event handlers of a live page get the join's context: web.Request is the join's request, and writing to web.ResponseWriter goes nowhere.

License

MIT

Documentation

Overview

Package web is a web framework for Vuka: routes, views and services are declared with decorators, and web.New gathers them into an app.

@web.Get("/pets/{id}")
@web.Template("pet.html")
func ShowPet(id int, store *PetStore) Result[Pet] { … }

func main() { web.New().Run(":8080") }

Everything a decorator declares can also be registered from plain Go (App.Get, App.Provide, …); see the README.

Index

• Constants
• Variables
• func AddPanel(name string, render func(notes []any) ui.Node)
• func Broadcast(ctx context.Context, topic string, msg any) error
• func Controller(prefix string) func(*vuka.Type)
• func Delete(path string) func(*vuka.Decl)
• func Env[T any](key string, def ...T) T
• func Get(path string) func(*vuka.Decl)
• func Handle(method, path string) func(*vuka.Decl)
• func Live(path string, opts ...LiveOption) func(*vuka.Type)
• func LoadEnv(files ...string) error
• func MustEnv[T any](key string) T
• func Note(ctx context.Context, panel string, v any)
• func NoteStatement(ctx context.Context, q Statement)
• func Patch(path string) func(*vuka.Decl)
• func Post(path string) func(*vuka.Decl)
• func Put(path string) func(*vuka.Decl)
• func RegisterCSS(name string, css []byte)
• func Request(ctx context.Context) *http.Request
• func Resolve[T any](a *App) (T, error)
• func ResponseWriter(ctx context.Context) http.ResponseWriter
• func Service(t *vuka.Type)
• func Template(f vuka.File, name ...string) func(*vuka.Decl)
• type App
  • func New(opts ...Option) *App
  • func (a *App) Broadcast(ctx context.Context, topic string, msg any) error
  • func (a *App) Build() error
  • func (a *App) Check(fn func(*App) error) *App
  • func (a *App) Delete(path string, fn any, opts ...RouteOption) *App
  • func (a *App) Eager(ctors ...any) *App
  • func (a *App) Get(path string, fn any, opts ...RouteOption) *App
  • func (a *App) Handle(method, path string, fn any, opts ...RouteOption) *App
  • func (a *App) Handler() http.Handler
  • func (a *App) Live(path string, component ui.Stateful, opts ...LiveOption) *App
  • func (a *App) OnStart(fn func(context.Context) error) *App
  • func (a *App) OnStop(fn func(context.Context) error) *App
  • func (a *App) Patch(path string, fn any, opts ...RouteOption) *App
  • func (a *App) Post(path string, fn any, opts ...RouteOption) *App
  • func (a *App) Provide(ctors ...any) *App
  • func (a *App) Put(path string, fn any, opts ...RouteOption) *App
  • func (a *App) Run(addr string) error
  • func (a *App) Start(ctx context.Context) error
  • func (a *App) Static(prefix string, fsys fs.FS) *App
  • func (a *App) Stop(ctx context.Context) error
  • func (a *App) Toolbar() bool
  • func (a *App) Use(mw ...Middleware) *App
• type Error
  • func BadRequest(msg string) *Error
  • func Status(status int, format string, args ...any) *Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Unwrap() error
• type LiveOption
  • func Layout(layout func(page ui.Node) ui.Node) LiveOption
• type Middleware
• type Option
  • func Check(fn func(*App) error) Option
  • func Dev() Option
  • func DotEnv(files ...string) Option
  • func Eager(ctors ...any) Option
  • func LiveKey(key []byte) Option
  • func LiveLayout(layout func(page ui.Node) ui.Node) Option
  • func LiveOrigins(patterns ...string) Option
  • func LiveProtocol(v int) Option
  • func LiveTokenTTL(d time.Duration) Option
  • func NoDotEnv() Option
  • func NoTailwind() Option
  • func NoToolbar() Option
  • func OnError(f func(w http.ResponseWriter, r *http.Request, e *Error, html bool)) Option
  • func OnStart(fn func(context.Context) error) Option
  • func OnStop(fn func(context.Context) error) Option
  • func Only(pkgs ...string) Option
  • func Options(opts ...Option) Option
  • func Provide(ctors ...any) Option
  • func Require(keys ...string) Option
  • func Tailwind(path string) Option
  • func WithRelay(r Relay) Option
  • func WithRouter(r Router) Option
• type OptionFunc
• type Redirect
  • func (r Redirect) Error() string
  • func (r Redirect) Render(context.Context, io.Writer) error
• type Relay
• type RouteOption
  • func Params(names ...string) RouteOption
  • func View(f vuka.File, name ...string) RouteOption
  • func Wrap(mw ...Middleware) RouteOption
• type Router
• type ServeMux
  • func NewServeMux() *ServeMux
  • func (m *ServeMux) Handle(method, pattern string, h http.Handler)
  • func (m *ServeMux) Param(r *http.Request, name string) string
  • func (m *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Starter
• type Statement
• type Stopper
• type URLParams
• type Uses
  • func Use(mw ...Middleware) Uses

Constants

const (

	// ToolbarHeader names the toolbar record of a development app's
	// response; the toolbar lists a page's fetch and XHR calls by it.
	ToolbarHeader = "X-Vuka-Toolbar"
	// DevDirEnv names the session directory vuka run passes the app: the
	// toolbar is on, and with -watch the directory's build.json says how
	// the next build is going.
	DevDirEnv = "VUKA_DEV_DIR"
)

const (

	// CSSEnv names the stylesheet file vuka run keeps up to date.
	CSSEnv = "VUKA_TAILWIND_CSS"
)

Variables

var (
	NotFound     = &Error{Status: http.StatusNotFound, Message: "not found"}
	Unauthorized = &Error{Status: http.StatusUnauthorized, Message: "unauthorized"}
	Forbidden    = &Error{Status: http.StatusForbidden, Message: "forbidden"}
	Conflict     = &Error{Status: http.StatusConflict, Message: "conflict"}
)

Functions

func AddPanel

func AddPanel(name string, render func(notes []any) ui.Node)

AddPanel adds a panel to the development toolbar: render draws it for a request from the values the request noted for it (Note), in order. A panel added again under the same name replaces it.

func Broadcast

func Broadcast(ctx context.Context, topic string, msg any) error

Broadcast delivers msg to the Update methods of every live component subscribed to topic, in every connected page of the app serving ctx (a request's, or a live event's), and sends each page what changed. A topic of "" reaches every component.

func Controller

func Controller(prefix string) func(*vuka.Type)

Controller makes a struct a service whose route methods are served under prefix.

func Delete

func Delete(path string) func(*vuka.Decl)

func Env

func Env[T any](key string, def ...T) T

Env returns the environment variable key as a T: a string, bool, integer, float, time.Duration, *url.URL (absolute), a type implementing encoding.TextUnmarshaler, or a slice of those (comma-separated). When key is unset or empty it returns def (or the zero value); when the value doesn't convert, it returns def too and the next Build or Start reports the error.

func Get

func Get(path string) func(*vuka.Decl)

func Handle

func Handle(method, path string) func(*vuka.Decl)

Handle declares a route for method and path: @web.Handle("OPTIONS", "/x"). Path segments in braces bind parameters of the same name: "/pets/{id}"; "{rest...}" matches the rest of the path.

func Live

func Live(path string, opts ...LiveOption) func(*vuka.Type)

Live serves a stateful component as a page at path, a GET route:

@web.Live("/rooms/{room}")
type Chat struct {
	vuka.Live
	Room  string     // a prop bound from the path segment, else ?room=
	Store *ChatStore // a prop of a provided type, injected
	log   []string   // state
}

Its exported fields of provided types are injected; the others that hold text bind from the path segment or query parameter of their name. The page is the component inside the app's layout (LiveLayout), or the one Layout names, or else a bare HTML document. Use adds middleware.

func LoadEnv

func LoadEnv(files ...string) error

LoadEnv reads env files into the process environment, as New does: for code that needs their values before New, such as options built from them. No files means the default list (see the README); a key is set only when the environment doesn't have it yet, and the first file listed wins over the later ones. Loading the same files again is a no-op, so New reading them afterwards changes nothing.

func MustEnv

func MustEnv[T any](key string) T

MustEnv is Env for values that must be there: it panics, naming key, when the variable is unset, empty or doesn't convert.

func Note

func Note(ctx context.Context, panel string, v any)

Note records v for the toolbar's panel named panel, drawn by the function AddPanel registered for it, else as a list of the values. It does nothing for a context that no development toolbar watches, so it can stay in production code.

func NoteStatement

func NoteStatement(ctx context.Context, q Statement)

NoteStatement records a statement the request of ctx (or its live page's socket message) ran, for the toolbar's SQL panel. It does nothing for a context that no development toolbar watches.

func Patch

func Patch(path string) func(*vuka.Decl)

func Post

func Post(path string) func(*vuka.Decl)

func Put

func Put(path string) func(*vuka.Decl)

func RegisterCSS

func RegisterCSS(name string, css []byte)

RegisterCSS registers a stylesheet the app serves at /_vuka/<name>; the one named "app.css" is linked from every full page. vuka build calls it from a file it generates in the main package, with the Tailwind CSS built for the binary.

func Request

func Request(ctx context.Context) *http.Request

Request is the request being served, from a context.Context a handler received: call decorators reach it through c.Context().

func Resolve

func Resolve[T any](a *App) (T, error)

Resolve returns the app's T, building it and its dependencies.

func ResponseWriter

func ResponseWriter(ctx context.Context) http.ResponseWriter

ResponseWriter is the response being written, from a handler's context.

func Service

func Service(t *vuka.Type)

Service makes a struct a dependency: a lazy singleton built from its fields, each injected by type.

func Template

func Template(f vuka.File, name ...string) func(*vuka.Decl)

Template renders a route's result with a view: a .templ file of the same package (its one exported component, or the one named) or an html/template file (its main template, or the one named). The order of @web.Template and the route's method decorator doesn't matter.

Types

type App

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

App is a web application: the routes, services and controllers declared with decorators, and whatever was added in code.

func New

func New(opts ...Option) *App

New makes an app of every route, service and controller declared so far (each app takes its own snapshot, with its own singletons). It first reads the env files into the process environment (see LoadEnv), so constructors and Start methods see their values through os.Getenv.

func (*App) Broadcast

func (a *App) Broadcast(ctx context.Context, topic string, msg any) error

Broadcast delivers msg to the components subscribed to topic, as the package's Broadcast does.

func (*App) Build

func (a *App) Build() error

Build resolves the app: every route's parameters, results and view, and the dependency graph. It reports every problem at once, before anything is served; Handler, Start and Run call it.

func (*App) Check

func (a *App) Check(fn func(*App) error) *App

Check adds fn to the checks Build runs once the routes are compiled; its error is reported with Build's own.

func (*App) Delete

func (a *App) Delete(path string, fn any, opts ...RouteOption) *App

func (*App) Eager

func (a *App) Eager(ctors ...any) *App

Eager adds constructors whose values Start builds (and starts, when they implement Starter) even when nothing needs them. Provided values that aren't functions always start; constructors otherwise only when needed.

func (*App) Get

func (a *App) Get(path string, fn any, opts ...RouteOption) *App

func (*App) Handle

func (a *App) Handle(method, path string, fn any, opts ...RouteOption) *App

Handle registers fn for method and path, bound as a decorated handler is.

func (*App) Handler

func (a *App) Handler() http.Handler

Handler is the app as an http.Handler, to serve or mount anywhere. It panics when Build fails.

func (*App) Live

func (a *App) Live(path string, component ui.Stateful, opts ...LiveOption) *App

Live serves component (a pointer to a stateful component, whose fields are the defaults) as a page at path, as the Live decorator does.

func (*App) OnStart

func (a *App) OnStart(fn func(context.Context) error) *App

OnStart adds fn to the app's start sequence, after the values supplied and the hooks added before it and before the values Start constructs.

func (*App) OnStop

func (a *App) OnStop(fn func(context.Context) error) *App

OnStop adds fn to the app's stop sequence, which runs in the reverse order of the start sequence: fn runs after everything started after it was added has stopped.

func (*App) Patch

func (a *App) Patch(path string, fn any, opts ...RouteOption) *App

func (*App) Post

func (a *App) Post(path string, fn any, opts ...RouteOption) *App

func (*App) Provide

func (a *App) Provide(ctors ...any) *App

Provide adds constructors (or ready values) to the app's container.

func (*App) Put

func (a *App) Put(path string, fn any, opts ...RouteOption) *App

func (*App) Run

func (a *App) Run(addr string) error

Run serves the app on addr (":" + $PORT, else ":8080", when empty) until SIGINT or SIGTERM, then shuts down gracefully and stops the services.

func (*App) Start

func (a *App) Start(ctx context.Context) error

Start builds every dependency the routes need and every Eager one, then runs the start sequence: each supplied or built value implementing Starter and each OnStart hook, in dependency order (supplied values and hooks as added, before the values built from constructors).

func (*App) Static

func (a *App) Static(prefix string, fsys fs.FS) *App

Static serves the files of fsys under prefix.

func (*App) Stop

func (a *App) Stop(ctx context.Context) error

Stop runs the stop sequence: each value implementing Stopper and each OnStop hook, in the reverse order of the start sequence.

func (*App) Toolbar

func (a *App) Toolbar() bool

Toolbar reports whether the app shows the development toolbar: for a library feeding it (NoteStatement) only then.

func (*App) Use

func (a *App) Use(mw ...Middleware) *App

Use adds app-wide middleware; the first added runs first.

type Error

type Error struct {
	Status  int
	Message string
	Err     error // the cause, never shown
}

Error is an error with an HTTP status. Returned by a handler (wrapped or not), it answers with that status and message: an HTML page for an HTML route, JSON otherwise.

func BadRequest

func BadRequest(msg string) *Error

BadRequest is a 400 error with msg.

func Status

func Status(status int, format string, args ...any) *Error

Status is an error answering with status and the formatted message.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(target error) bool

Is matches another *Error of the same status: errors.Is(err, web.NotFound).

func (*Error) Unwrap

func (e *Error) Unwrap() error

type LiveOption

type LiveOption interface {
	// contains filtered or unexported methods
}

LiveOption configures a page declared with Live.

func Layout

func Layout(layout func(page ui.Node) ui.Node) LiveOption

Layout wraps a Live page's component: the page is layout(component).

type Middleware

type Middleware = func(http.Handler) http.Handler

Middleware wraps an http.Handler.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures an App.

func Check

func Check(fn func(*App) error) Option

Check adds a check Build runs; see App.Check.

func Dev

func Dev() Option

Dev shows the messages of internal errors in responses; so does the environment variable VUKA_ENV=development.

func DotEnv

func DotEnv(files ...string) Option

DotEnv replaces the env files New reads (see LoadEnv); the first listed wins. Relative paths are read from the working directory, or the nearest parent up to the module root holding one of them.

func Eager

func Eager(ctors ...any) Option

Eager provides constructors whose values are built and started by Start even when no route needs them (workers, schedulers).

func LiveKey

func LiveKey(key []byte) Option

LiveKey is the key signing live pages' join tokens. Without it each app draws a random one, so a page rendered by one process can't join another: set it when several replicas serve the app.

func LiveLayout

func LiveLayout(layout func(page ui.Node) ui.Node) Option

LiveLayout is the layout of every Live page without its own.

func LiveOrigins

func LiveOrigins(patterns ...string) Option

LiveOrigins lets pages of other origins open live connections: host patterns as path.Match takes them ("app.example.com", "*.example.com"). By default only the app's own origin may.

func LiveProtocol

func LiveProtocol(v int) Option

LiveProtocol caps the live protocol version the app speaks: 2 (render trees: a page gets each component's statics once, then only the dynamics that changed) by default, or 1 (each changed component's HTML). A page asks for the newest it knows and gets at most this; v2 also needs a Vuka live session that speaks it, else pages get v1.

func LiveTokenTTL

func LiveTokenTTL(d time.Duration) Option

LiveTokenTTL is how long a rendered live page may (re)join; 12 hours by default. A page older than that reloads when it reconnects.

func NoDotEnv

func NoDotEnv() Option

NoDotEnv keeps New from reading env files.

func NoTailwind

func NoTailwind() Option

NoTailwind turns the app's stylesheet off: pages get no link to /_vuka/app.css and the vuka command builds none.

func NoToolbar

func NoToolbar() Option

NoToolbar turns the development toolbar off.

func OnError

func OnError(f func(w http.ResponseWriter, r *http.Request, e *Error, html bool)) Option

OnError replaces the error page and JSON error body.

func OnStart

func OnStart(fn func(context.Context) error) Option

OnStart adds a hook Start runs; see App.OnStart.

func OnStop

func OnStop(fn func(context.Context) error) Option

OnStop adds a hook Stop runs; see App.OnStop.

func Only

func Only(pkgs ...string) Option

Only limits the declared routes, services and controllers an app takes to those of the given packages (import paths; "main" for the main package).

func Options

func Options(opts ...Option) Option

Options is one Option applying opts in order; nil options are skipped.

func Provide

func Provide(ctors ...any) Option

Provide adds constructors to the app's container: func(deps…) T or func(deps…) (T, error). A value that isn't a function is provided as is.

func Require

func Require(keys ...string) Option

Require fails Build when one of the environment variables is unset or empty, naming each missing one and the env files looked for.

func Tailwind

func Tailwind(path string) Option

Tailwind names the project's Tailwind stylesheet, relative to the module root, when it isn't app.css or styles/app.css. The vuka command reads the path from the source, so it must be a string literal.

func WithRelay

func WithRelay(r Relay) Option

WithRelay sends the app's broadcasts through r instead of delivering them in-process only.

func WithRouter

func WithRouter(r Router) Option

WithRouter serves the app's routes with r instead of net/http's ServeMux.

type OptionFunc

type OptionFunc func(*App)

OptionFunc is an Option written as a function of the App, for libraries defining their own options: it runs inside New, before Build, and may call any of the App's methods (Provide, Use, Handle, OnStart, Check, …).

type Redirect

type Redirect string

Redirect, returned by a handler as its result or as its error, redirects to the URL: 302 for GET and HEAD, 303 See Other otherwise. It is also a vuka.Node, so a handler returning a page can redirect instead.

func (Redirect) Error

func (r Redirect) Error() string

func (Redirect) Render

func (r Redirect) Render(context.Context, io.Writer) error

type Relay

type Relay interface {
	Publish(ctx context.Context, topic string, msg any) error
	Subscribe(deliver func(topic string, msg any))
}

Relay carries broadcasts between the replicas of an app: Publish sends a message to every replica, and each calls the function Subscribe was given with what arrives (its own messages included). Encoding the messages, whose dynamic types pick the Update methods they reach, is the relay's business.

type RouteOption

type RouteOption func(*routeSpec)

RouteOption configures a route registered in code.

func Params

func Params(names ...string) RouteOption

Params names a handler's parameters in order, which reflection can't see: scalar parameters bind by name.

func View

func View(f vuka.File, name ...string) RouteOption

View renders the route's result with a view, as @web.Template does.

func Wrap

func Wrap(mw ...Middleware) RouteOption

Wrap adds middleware to the route, as @web.Use does.

type Router

type Router interface {
	http.Handler
	Handle(method, pattern string, h http.Handler)
	Param(r *http.Request, name string) string
}

Router matches requests to routes. Patterns use the canonical syntax: "/pets/{id}" binds a segment, "/files/{path...}" the rest of the path, and a pattern matches its path exactly. Param returns a bound value for a request the router dispatched.

type ServeMux

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

ServeMux is the default Router: net/http's ServeMux with Go 1.22 patterns.

func NewServeMux

func NewServeMux() *ServeMux

func (*ServeMux) Handle

func (m *ServeMux) Handle(method, pattern string, h http.Handler)

func (*ServeMux) Param

func (m *ServeMux) Param(r *http.Request, name string) string

func (*ServeMux) ServeHTTP

func (m *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Starter

type Starter interface{ Start(context.Context) error }

Starter is a provided value with work to do when the app starts: Run calls Start in dependency order.

type Statement

type Statement struct {
	SQL      string
	Args     []any
	DB       string // the database's name
	Start    time.Time
	Duration time.Duration
	Rows     int64 // rows affected; -1 for a query
	Err      error
	// Refused is a statement the database layer refused before sending it;
	// Err says why.
	Refused bool
}

Statement is a statement for the toolbar's SQL panel: what a database layer passes NoteStatement. orm's ormweb reports the ORM's statements by itself.

type Stopper

type Stopper interface{ Stop(context.Context) error }

Stopper is a provided value with work to do when the app stops: Stop is called in the reverse order of construction.

type URLParams

type URLParams struct{}

URLParams, embedded in a struct, makes it the parameters a Live page's Update method takes when the page is patched — moved to another URL of its route, the component staying mounted:

type ShelfParams struct {
	web.URLParams
	Page int // ?page=
}

func (s *Shelf) Update(p ShelfParams) { s.load(p.Page) }

Its fields bind from the new URL as the component's props do (path segment, else query parameter, of their name); the component's props are bound again too. Update runs before the patch renders, and an error it returns is the patch's, shown as a handler's. Mount, not Update, sees the first URL.

type Uses

type Uses func(*vuka.Decl)

Uses is what Use returns: a declarer adding middleware to one route, and an Option adding it to the whole app.

func Use

func Use(mw ...Middleware) Uses

Use adds HTTP middleware, the first given outermost: @web.Use(mw) on a route, or web.New(web.Use(mw)) for every request of the app.