Installation
Check your Go version
lttr needs Go 1.25 or newer.
go version
Configure private module access
sulv-io/lttr is a private repository. The public module proxy and checksum database cannot read it, so go get fails until you tell Go to fetch it directly and give Git a credential that can read it. You do this once per machine.
Mark the module as private
go env -w GOPRIVATE='github.com/sulv-io/*'
GOPRIVATE sets GONOPROXY and GONOSUMDB to the same pattern, so Go fetches anything under github.com/sulv-io/ straight from GitHub and skips the checksum lookup that would fail on a repository it cannot see.
Let Git authenticate
Go fetches modules over HTTPS. Rewrite those URLs to carry a token that can read the repository:
git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/sulv-io/".insteadOf "https://github.com/sulv-io/"
If you already use an SSH key with GitHub, rewrite to SSH instead and no token is stored:
git config --global url."git@github.com:sulv-io/".insteadOf "https://github.com/sulv-io/"
Verify
go env GOPRIVATE
git ls-remote https://github.com/sulv-io/lttr HEAD
The first prints github.com/sulv-io/*. The second prints a commit hash. If it asks for a password or reports Repository not found, the credential is the problem, not Go.
~/.gitconfig. On a workstation prefer SSH; in CI, inject a short-lived token as an environment variable.Add the module
go get github.com/sulv-io/lttr
lttr depends on two modules besides the standard library: goldmark, which the comark parser extends, and yaml.v3, which reads frontmatter.
Most services import the root package and two leaf packages:
| Import path | What it holds |
|---|---|
github.com/sulv-io/lttr | Compile, Template, Renderer, Config, Family, Registry, Message, Router, SMTP |
github.com/sulv-io/lttr/data | Typed template values: Money, Exact, Receipt, Product, StockItem |
github.com/sulv-io/lttr/theme | The palette, font and brand types behind lttr.Theme |
github.com/sulv-io/lttr/mapbox | Mapbox Static Images URLs for the map module (optional) |
The pipeline packages (comark, ir, layout, render/html, render/text) are exported for tools and tests. You rarely import them directly.
go list -m github.com/sulv-io/lttr.Install the CLI
go install github.com/sulv-io/lttr/cmd/lttr@latest
lttr -h
usage: lttr <command> [flags]
commands:
preview render every example to a directory with an index page
render write one example's .eml to stdout
lint compile template files and print errors and warnings
tags list a template's merge tags and bindings
serve live preview that recompiles templates on every request
Run "lttr <command> -h" for a command's flags.
The CLI works on the worked example in examples/quiet: it compiles templates against the example's data types and renders them with its theme and families. Use it to see the design, try a module or check a change to the library. lttr serve reads the templates from examples/quiet/templates by default, so run it from a checkout of the repository or pass -dir. In your own service, the compile checks run when your package initialises, so go test catches a broken template. See CLI and Goldens and testing.
Next steps
- Quick start builds, renders and sends a complete email in one file.
- Comark syntax covers what a template can contain.