HTML Views

Copper renders server-side HTML using Go templates. Layouts, pages, and partials are all embedded into your binary.

New projects default to a React frontend with Inertia; see Frontend. This page covers classic server-rendered Go templates, which are a great fit for simpler apps and HTMX-style interactivity.

Template Directory

Templates live under web/src in three conventional directories:

web/src/
├── layouts/
│   └── main.html        # page shell: <html>, <head>, nav
├── pages/
│   ├── index.html
│   └── rocket.html
└── partials/
    └── rocket-card.html # reusable fragments

A layout defines the shell and renders the page inside it:

web/src/layouts/main.html

<!DOCTYPE html>
<html>
<head>
    <title>Mission Control</title>
</head>
<body>
    {{ template "content" . }}
</body>
</html>

web/src/pages/rocket.html

{{ define "content" }}
<h1>{{ .Rocket.Name }}</h1>
<p>Status: {{ .Rocket.Status }}</p>
{{ end }}

Rendering Pages

Copper provides chttp.HTMLReaderWriter for writing HTML responses. Inject it into your router and call WriteHTML:

type NewRouterParams struct {
	Rockets *Svc
	HTML    *chttp.HTMLReaderWriter
	Logger  clogger.Logger
}

func (ro *Router) HandleRocketPage(w http.ResponseWriter, r *http.Request) {
	rocket, err := ro.rockets.Get(r.Context(), chttp.URLParams(r)["id"])
	if err != nil {
		ro.html.WriteHTMLError(w, r, err)
		return
	}

	ro.html.WriteHTML(w, r, chttp.WriteHTMLParams{
		PageTemplate: "rocket.html",
		Data:         map[string]any{"Rocket": rocket},
	})
}

LayoutTemplate defaults to main.html and StatusCode to 200; you may set either explicitly when needed. On errors, an appropriate page will automatically be chosen for you: internal-error.html for 500s and not-found.html for 404s.

Template Functions

Every template has the full Sprig function library available, including upper, date, and mustToRawJson. You may add your own functions using chttp.HTMLRenderFunc. Since render funcs receive the current request, they can expose per-request state such as the signed-in user:

web/wire.go

func HTMLRenderFuncs() []chttp.HTMLRenderFunc {
	return []chttp.HTMLRenderFunc{
		{
			Name: "currentUser",
			Func: func(r *http.Request) (any, error) {
				return func() *sessions.User {
					return sessions.UserFromCtx(r.Context())
				}, nil
			},
		},
	}
}

<p>Welcome back, {{ (currentUser).Name }}</p>

Partials

Partials in web/src/partials are reusable fragments. Render one inside any template with the built-in partial function:

{{ range .Rockets }}
    {{ partial "rocket-card" . }}
{{ end }}

You may also write a partial directly as a response, which works well for HTMX-style updates that swap a fragment into the page:

func (ro *Router) HandleRocketStatus(w http.ResponseWriter, r *http.Request) {
	rocket, err := ro.rockets.Get(r.Context(), chttp.URLParams(r)["id"])
	if err != nil {
		ro.html.WriteHTMLError(w, r, err)
		return
	}

	ro.html.WritePartial(w, r, chttp.WritePartialParams{
		Name: "rocket-card",
		Data: rocket,
	})
}

Static Assets

Files in web/public are served under /static/. For example, web/public/logo.svg is available at /static/logo.svg. In production these files are embedded into your binary, while in development they are read from disk.

Local Development

Two config flags make template development pleasant, and both are enabled in config/dev.toml for new projects:

[chttp]
use_local_html = true     # read templates & static files live from ./web — no rebuild
render_html_error = true  # show the actual error in the browser instead of a blank 500

Single-Page Apps

If your frontend handles its own routing, you may configure every unmatched GET request to render index.html:

[chttp]
enable_single_page_routing = true

API-Only Apps

If your application doesn’t serve HTML at all, use chttp.WireModuleEmptyHTML in place of the HTML and static dir bindings; it satisfies wire with empty stand-ins. Projects created with -frontend=none are configured this way.

Getting Started

The Basics

Architecture

HTTP

Database

Frontend

Digging Deeper

Reference

Template Directory

Rendering Pages

Template Functions

Partials

Static Assets

Local Development

Single-Page Apps

API-Only Apps

​Template Directory

​Rendering Pages

​Template Functions

​Partials

​Static Assets

​Local Development

​Single-Page Apps

​API-Only Apps

Template Directory

Rendering Pages

Template Functions

Partials

Static Assets

Local Development

Single-Page Apps

API-Only Apps