samhennessy/hlive/hlive-project

Structuring an HLive project

HLive's _example/ demos are single files to keep them readable. A real app spreads across packages. This is the recommended layout (modeled on the hlive_docs app), using hhtml for markup — see the hlive-hhtml and hlive-core skills for the building blocks.

Layout

myapp/
├── main.go              # entry point: routing + static assets
├── go.mod               # module github.com/you/myapp
├── justfile             # build/run recipes (optional)
├── page/                # one file per page; package "page"
│   ├── home.go          #   func Home() *l.Page
│   ├── about.go         #   func About() *l.Page
│   ├── components.go    #   shared unexported components: header(), footer()
│   └── demo/            #   sub-package for a group of related routes
│       └── clicker.go   #   func Clickers() http.Handler
├── src/                 # plain Go helper packages (no HLive), unit-testable
│   └── .../
└── assets/              # css/js/images served at /assets/
    └── main.css

Keep it flat — most logic lives in page/. Add a sub-package under page/ only to group a feature's routes.

Entry point — main.go

Use the standard library net/http; HLive's PageServer is just an http.Handler. Register each page factory, then serve static files.

package main
 
import (
    "log"
    "net/http"
 
    l "github.com/SamHennessy/hlive"
    "github.com/you/myapp/page"
    "github.com/you/myapp/page/demo"
)
 
func main() {
    http.Handle("/", l.NewPageServer(page.Home))
    http.Handle("/about", l.NewPageServer(page.About))
    http.Handle("/demos/clickers", demo.Clickers())
 
    // static assets, e.g. /assets/main.css -> ./assets/main.css
    fs := http.FileServer(http.Dir("./assets"))
    http.Handle("/assets/", http.StripPrefix("/assets/", fs))
 
    log.Println("listening on :3000")
    if err := http.ListenAndServe(":3000", nil); err != nil {
        log.Fatal(err)
    }
}

l.NewPageServer takes a page factory func() *l.Page. For routes that need extra wiring (their own handler, query params), expose a func() http.Handler instead (as demo.Clickers() does).

Pages — the page package

One exported, PascalCase factory per page, each returning *l.Page. Build the <head> (title + stylesheets) and <body> with hhtml, composing shared components:

package page
 
import (
    l "github.com/SamHennessy/hlive"
    . "github.com/SamHennessy/hlive/hhtml"
)
 
func Home() *l.Page {
    page := l.NewPage()
    page.DOM().Title().Add("MyApp — Home")
    page.DOM().Head().Add(Link(Rel("stylesheet"), Href("/assets/main.css")))
 
    page.DOM().Body().Add(
        Div(Class("container"),
            header(),
            Main(Class("main"),
                H1("Welcome"),
                P("Built with HLive."),
            ),
        ),
    )
    return page
}

There is no central layout wrapper; the per-page head/shell boilerplate is repeated (or factored into a small helper you call from each page). One *l.Page instance serves one connected user.

Reusable components

Shared UI is just unexported, camelCase functions returning l.Adder (the interface hhtml builders return), kept in page/components.go:

func header() l.Adder {
    return Header(Class("header"),
        Div(Class("logo"), "MyApp"),
        Nav(
            Ul(Class("nav-links"),
                Li(A(Href("/"), "Home")),
                Li(A(Href("/about"), "About")),
            ),
        ),
    )
}

Call them inside page factories: Body().Add(Div(header(), ...)).

Where state lives

• Page-local reactive values: l.Box(...) / l.NewLockBox[T](...), captured in

the page factory's closure and updated from l.On handlers.

• Feature state that spans components or goroutines (live demos, real-time

feeds): a struct holding the boxes plus methods, often with hlivekit.PubSub for fan-out. See the hlivekit skill and hlive_docs/page/demo/clicker.go.

Keep non-UI logic (parsing, calculations, data access) in plain Go packages under src/ so it's unit-testable without a browser.

Static assets

Put CSS/JS/images under assets/ and serve them as shown in main.go. Link them in each page's <head> with Link(Rel("stylesheet"), Href("/assets/...")).

Build & run

A justfile keeps commands handy (or use go directly):

build:
    go build -o ./deploy/server .
 
run:
    go run .

go run . from the module root is enough for local development; the server serves ./assets relative to its working directory.

Reference

hlive_docs/main.go, hlive_docs/page/home.go, hlive_docs/page/components.go, hlive_docs/page/demo/clicker.go, hlive_docs/justfile. (hlive_docs is a work-in-progress and is mid-migration to hhtml — follow the structure, and prefer hhtml for new markup.) For testing pages from a page package, see the hlive-testing skill.