A small application
This walkthrough builds a desk with two pages. Notes is a
form and a table: Add appends a row. About is a short
read-only page. The directory layout is the URL layout, so
the pages are served at /notes and
/about.
The list of notes lives in the browser tab that created it. A reload starts from an empty table. There is no database in this version, and pages are ordinary Go values. A later component syntax will lower to the same structs.
The finished project looks like this:
desk/
app.json
main.go
about/
page.go
notes/
page.go
Install the toolchain
Bolero's compiler is the go command. Download
the archive for your machine from the
latest release.
Linux AMD64 is go1.26.3.linux-amd64.tar.gz,
Linux ARM is go1.26.3.linux-arm64.tar.gz,
and Mac ARM is go1.26.3.darwin-arm64.tar.gz.
Windows AMD64 is go1.26.3.windows-amd64.zip.
SHA256SUMS in that release lists the checksum
of each archive.
Unpack the archive. It contains a go directory,
with bin/go and bin/gofmt inside.
On Linux and Mac, put that bin directory first
on PATH, and stay on this toolchain. The
commands below are for Linux AMD64. Linux ARM and Mac ARM
use the same commands with their own archive:
tar -xzf go1.26.3.linux-amd64.tar.gz export PATH="$PWD/go/bin:$PATH" export GOTOOLCHAIN=local
On Windows, unzip go1.26.3.windows-amd64.zip
in PowerShell, add its bin directory to
Path, and set GOTOOLCHAIN to
local:
tar -xf go1.26.3.windows-amd64.zip $env:Path = "$PWD\go\bin;$env:Path" $env:GOTOOLCHAIN = "local"
go version then reports go1.26.3.
Create the project
mkdir desk cd desk go mod init example.com/desk
go mod init writes app.json and
nothing else: no main file, and no go.sum.
go.sum appears later, beside
app.json, when a command downloads a
dependency. This desk uses only the standard library and
bolero/ui, which ship with the toolchain, so
there is no go.sum.
app.json
{
"module": "example.com/desk",
"go": "1.26.3",
"version": "0.1.0",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "you@example.com"
}
]
}
Open the file and set the application name, a one-line
description, and yourself as the author. name
is the label in the navigation. version,
description, license, and
authors describe the project; the build leaves
them unused. Leave go as the version init wrote.
The toolchain rewrites the file in this key order.
app.json
{
"module": "example.com/desk",
"go": "1.26.3",
"name": "Desk",
"version": "0.1.0",
"description": "A two-page notes desk",
"license": "MIT",
"authors": [
{
"name": "Ada Lovelace",
"email": "ada@example.com"
}
]
}
A directory that contains both app.json and
go.mod is an error. Dependencies you download
keep their own go.mod files. The module path,
here example.com/desk, is the import prefix
for the project's own packages.
The server
main.go
package main
import "bolero/ui"
func main() {
ui.ListenAndServe("")
}
An empty address listens on 127.0.0.1:8080.
When BOLERO_ADDR is set, that address is used
instead. The address is an environment variable, and it
stays out of app.json.
main does not import notes or
about. While building an app.json
module, the go command finds every package that declares
Page and registers it. go run .
and go build do this. A command that names
only main.go compiles that one file, and the
pages are absent.
The notes page
Create notes/page.go. The package directory,
with the module path removed, is the URL
/notes.
PageTitle is the navigation label. Without it,
the label is still Notes, taken from the last path segment.
PageOrder sorts the navigation. About uses 2,
so Notes comes first. Equal orders are sorted by path.
Page runs once each time the page is opened.
The value it returns is kept for that browser tab. The
handler closes over list, and a later click
replaces list.Rows, so list has
to be the table stored in the page.
notes/page.go
package notes
import "bolero/ui"
const PageTitle = "Notes"
const PageOrder = 1
func Page(c *ui.Context) ui.Page {
list := &ui.Table{
Name: "notes",
FieldGroups: []ui.FieldGroup{{
Fields: []ui.Field{
{Name: "title", Label: "Title"},
{Name: "body", Label: "Note"},
},
}},
}
return ui.Page{
Title: "Notes",
Groups: []ui.Group{{
Title: "New note",
Items: []ui.Elem{
ui.Form{
Name: "note",
FieldGroups: []ui.FieldGroup{{
Fields: []ui.Field{
{Name: "title", Label: "Title", Required: true},
{Name: "body", Label: "Note", Required: true},
},
}},
},
ui.ActionPicker{
Name: "noteActions",
Actions: []ui.Action{{
Name: "add",
Label: "Add",
Form: "note",
OnClick: func(c *ui.Context) {
title, _ := c.Input("note", "title")
body, _ := c.Input("note", "body")
list.Rows = append(list.Rows, []string{title, body})
c.ClearInput("note", "title")
c.ClearInput("note", "body")
},
}},
},
list,
},
}},
}
}
The form's name is note. Field names are
unique inside that form. Both fields are required. An empty
Title or Note is rejected, and the error is shown on the
field. The zero field kind is text. The other kinds are
integer, decimal, selection, date, time, date-and-time, and
boolean.
The button lives on an action picker. Form set
to "note" ties the button to that form:
OnClick runs when every field is valid.
Otherwise the page is drawn again with the errors.
After a successful add, ClearInput empties the
two fields. Widget names are unique on the page, and a name
must contain no slash. A missing name or a duplicate is
reported when the page is rendered.
OnClick runs while the view is locked. It
returns before any other goroutine uses the
Context.
The about page
about/page.go is served at /about.
Value is the text already in the field.
ReadOnly ignores an edit and draws the stored
value again.
about/page.go
package about
import "bolero/ui"
const PageTitle = "About"
const PageOrder = 2
func Page(c *ui.Context) ui.Page {
return ui.Page{
Title: "About",
Groups: []ui.Group{{
Title: "This desk",
Items: []ui.Elem{
ui.Form{
Name: "info",
FieldGroups: []ui.FieldGroup{{
Fields: []ui.Field{
{
Name: "kept",
Label: "Notes",
Value: "Kept in this browser tab",
ReadOnly: true,
},
},
}},
},
},
}},
}
}
A page file may be page.go or
page.bo. The function is the same either way.
These directories are never pages: internal,
testdata, vendor, names that start
with a dot or an underscore, the module root, and any
package named main.
Run it
From the desk directory:
go run .
The process logs
listening on http://127.0.0.1:8080.
Open that address.
/ shows the name Desk and the side navigation,
with no groups. /notes is the form.
/about is the read-only page. The navigation
lists Notes, then About.
Leave a field empty and press Add. The field shows
required, and the table stays empty. Fill both
fields and press Add. A row appears, and the fields clear.
A click on a column header sorts the rows on screen. The
order stored in Rows stays the order the page
appended. A second browser tab has its own empty table.
Interrupt, SIGTERM, or SIGQUIT
stops the process.
How a page stays in sync
The server renders the page to HTML. A field change or a button click goes back over a WebSocket, and the reply replaces the markup for that part of the page. The browser sends a field when it is left, and a button when it is clicked. It does not send each keystroke.
The session cookie is bolero_session. Its value
is 32 random bytes, hex-encoded, and the cookie is
HttpOnly and SameSite=Lax.
Secure is set when the request arrived on TLS.
A session with no requests for 12 hours is dropped. The
store is in memory.
There is no login in this version, so every page is served
to whoever can open the server. The default address is
loopback. HTML is escaped. A panic in Page or
in a handler is recovered: the stack is logged, and the
page shows the panic value.
A record id is a query parameter. Page reads it
with c.Query().Get("id"), so
/notes?id=42 is one note.
/notes/42 is a different URL. This desk has no
package there, so that path is a 404 in the same
navigation. A package in notes/archive would
be served at /notes/archive.