good

A pretty good web scaffold for Golang

The good tool embeds a web GUI in a Golang project.

• Plain, grok-able code
• Self contained with minimal dependencies
• Fully embedded assets and templates
• Classic HTML template composition
• Boring tech, fewer surprises

[ CLI Overview ~ Building GUIs ~ Starter Templates ~ Developer Notes ]

Overview

The good scaffold command outputs a web GUI setup to a sub package of a Go project. The scaffold is geared towards web consoles and admin tools for backend services or daemons.

Pages are added using the good page command, which has a starter template feature to speed-up development. The scaffold package is unobtrusive so that it can be embedded in an existing codebase without difficulty.

TLDR; quickstart

$ go get github.com/rur/good
$ cd ~/path/to/mygoproject
[mygoproject]$ good scaffold ./myportal
[mygoproject]$ go generate ./myportal/...
[mygoproject]$ go run ./myportal --dev --port 8000

Visit localhost:8000 and take it from there.

CLI Overview

The CLI tools will generate HTML and Golang files that you can modify & refactor to suit your needs.

Tip: Use the -h flag for help with commands

Good Scaffold <scaffoldPkg>

This snippet creates a new scaffold at ./portal, relative to the current Go module.

$ good scaffold ./portal

Good Page <scaffoldPkg> <pagename>

Adds a new 'settings' page to our ./portal example.

$ good page ./portal settings

Good Pages {gen list delete} ...

Utilities for site pages. For example, list the pages to stdout

$ good pages list ./portal
home
settings

Good Routes Gen <pagePkg>

Update the routing code for the specified scaffold page package.

Generate a routes.go file from the routemap.toml config file in the target page. This contains layout and endpoint plumbing code that uses the Treetop library.

$ good routes gen ./portal/page/settings

Good Starter <outdir>

$ good starter ./portal/my-page-starter

Create a directory and populate it with code template files for a customized starter page. This can be used with the Good Page command like so.

$ good page ./portal mynewpage --starter ./portal/my-page-starter

Building GUIs

We'll add a web console in the next version

– Backend Developer

This scaffold reduces the overhead of adding a GUI to your project in the following ways:

• Quick-start page templates:
  • Starter examples for common workflows
  • Use a suitable CSS toolkit
• Code generation with TOML config:
  • Static plumbing code for page routes
  • Take advantage of the type checker
• Minimize code outside of Golang,
  • Make it convenient to do templating on the server-side
  • Use your available project code

Low Cost Interactivity

The scaffold server is able to serve HTML fragments that passively update the current page layout. Many modern UX requirements can be satisfied with fragment DOM updates while keeping business logic entirely on the sever side. This reduces the reliance on APIs to support a modern user journey, avoiding some of the overhead of a typical webapp.

Partial rendering is configured using the _partial or _fragment flags in the Routemap config file.

Check out the example starter page

Routemap Layouts

Routemaps combine code generation with the classic 'layout hierarchy' approach to web templating. The Treetop library is used to bind template files and handlers to HTTP endpoints.

The good routes gencommand uses a TOML config to generate the endpoint plumbing code for a page.

_ref = "base"
_template = "/templates/base.html.tmpl"
_handler = "baseHandler"

  [[content]]
  _ref = "main-content"
  _template = "/templates/content/main.html.tmpl"
  _handler = "mainContentHandler"
  _path = "/example"

  [[content]]
  _ref = "other-content"
  _template = "/templates/content/other.html.tmpl"
  _handler = "otherContentHandler"
  _path = "/other-example"

^ This basic example has two endpoints that share the same base view. Templates can be nested further. Try the scaffold and explore some working examples.

Starter Templates

Page boilerplate can be loaded from a local folder or using one of the built-in options.

Built-in page starter

See the starter#good-starter for details about what built-in options are available.

good page ./mysite mynewpage --starter :bootstrap5/layout

Custom page starter

Commit a starter page to your project with custom boilerplate. Very useful if you like to do a lot of prototyping!

The good starter command will help you to get set up.

Developer Notes

1. CLI that generates plain, grok-able code

The output is mostly vanilla Golang and HTML templates. We embrace some redundancy so that the code will be more static, easier to read and customize. This works well with the Golang type system and tooling, which makes refactoring a cinch at the cost of some extra typing.

2. Self-contained server with minimal dependencies

We avoid a lot of mandatory dependencies by making the most of the standard library. There is no plugin system; if you are familiar with Golang you can rely on an easy-to-follow codebase to integrate your chosen libraries manually.

3. Embedded assets

The //go:embed compiler directive ^[≥go1.16] is configured so that web server assets can be fully embedded at compile time. This gives you the option to distribute your GUI as a self-contained binary or embedded in an another Go server.

4. Classic HTML template composition

HTML template composition has excellent support in Golang. This scaffold uses the Treetop library to help organize templates and handlers, with the added benefit of fragment hot-swapping for enhanced interactivity.

5. Boring tech, fewer surprises

The scaffold is more of a workhorse than a unicorn; we embrace some practical limitations for the purpose of tight server-side integration. Take care to judge the limitations for yourself and decide what is right for your project.