Bolero

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.