Check is a Go library and CLI for statically type-checking text/template and html/template. It catches template/type mismatches early, making refactoring safer when changing types or templates.
It includes a CLI and a VS Code extension.
If all your ExecuteTemplate or Execute calls use a static type for the data argument, you can use the CLI directly:
go get -tool github.com/tooolbox/check/cmd/check-templates
go tool check-templates ./...Flags:
-v— list each call with position, template name, and data type-w— enable warnings for potential issues (see Warnings below)-C dir— change working directory before loading packages-o format— output format:tsv(default) orjsonl--mcp— run as an MCP server over stdio (for AI agent integration)--version— print version and exit
The CLI works by statically analyzing your Go source code. It traces each ExecuteTemplate and Execute call back to the variable that holds the *template.Template, then follows that variable's initialization chain to find the template files. This means:
-
ExecuteTemplatemust use a string literal for the template name (second argument). Calls that pass a variable or expression will produce a warning (with-w) and be skipped.Executecalls are also supported — the template name is inferred from the receiver's root template. -
Template initialization works best with static arguments. File paths passed to
ParseFiles, glob patterns passed toParseGlob, and embed patterns passed toParseFSare ideally string literals. However, the tool can also traceembed.FSvariables through function parameters across packages, resolvefs.Globcalls against embedded file lists, and handle spread[]stringvariables and per-page template map construction. -
Supported initialization patterns:
template.Must(template.ParseFiles("a.html", "b.html"))template.Must(template.ParseGlob("templates/*.html"))template.Must(template.ParseFS(fs, "*.html"))template.New("name").ParseFiles("a.html")- Chained calls:
.Funcs(...),.Option(...),.Delims(...),.Parse(...) - Additional
.ParseFiles(...),.ParseGlob(...), or.ParseFS(...)calls on an already-initialized template variable
The -w flag enables warnings for issues that are not type errors but may indicate bugs. All warnings are printed to stderr.
When dot is a pointer type (e.g. *Page), accessing a field like .Title will panic at runtime if dot is nil. The tool warns unless the access is guarded by {{with}}, {{if}}, or the and short-circuit pattern.
type Page struct { Title string }
func render(p *Page) {
_ = templates.ExecuteTemplate(w, "index.gohtml", p)
}Warns — accessing .Title on a pointer without a nil guard:
{{.Title}}
OK — guarded with {{with}}:
{{with .}}
{{.Title}}
{{end}}
OK — guarded with {{if}}:
{{if .}}
{{.Title}}
{{end}}
OK — guarded with and short-circuit (Go's and returns the first falsy value without evaluating the rest):
{{if and .User (eq .User.Role "admin")}}
{{.User.Username}}
{{end}}
Guards also work through $ references ($.User), sub-template calls ({{template "nav" .}}), and inside {{range}} blocks.
For pointer-typed struct fields that are always initialized before being passed to a template, you can suppress W003 with a struct tag:
type PageData struct {
Title string
S *Strings `templatecheck:"nonil"`
User *models.User `templatecheck:"nonil"`
}The tag is respected for direct access (.S.AppName), variable assignment ($s := .S then $s.AppName), $ references ($.User.Role), and embedded structs.
When dot is interface{} or any, field access cannot be verified at compile time.
func render(data any) {
_ = templates.ExecuteTemplate(w, "page.gohtml", data)
}Warns — field access on an interface type:
{{.Title}}
Templates loaded via ParseFS, ParseFiles, or ParseGlob that are never referenced by any ExecuteTemplate call or {{template}} action.
//go:embed *.gohtml
var source embed.FS
var templates = template.Must(template.New("app").ParseFS(source, "*"))
func render() {
_ = templates.ExecuteTemplate(w, "index.gohtml", data)
}Warns if unused.gohtml exists in the embed but is never referenced:
main.go:5:5: template "unused.gohtml" is defined but never referenced (W002)
ExecuteTemplate must be called with a string literal for the template name. Calls with a variable or expression cannot be checked statically.
// Warns — template name is a variable, not a string literal:
name := getTemplateName()
_ = templates.ExecuteTemplate(w, name, data)
// OK — template name is a string literal:
_ = templates.ExecuteTemplate(w, "index.gohtml", data)Variables declared with $x := ... that are never referenced in the template.
{{$x := .Title}} {{/* $x is never used */}}
<h1>{{.Title}}</h1>
Branches with literal true, false, or nil conditions that can never execute.
{{if true}}always{{else}}never reached (W006){{end}}
{{if false}}never reached (W006){{end}}
A sub-template invoked from multiple {{template}} call sites with incompatible data types.
{{template "header" .Page}} {{/* passes Page */}}
{{template "header" .Count}} {{/* passes int — W007 */}}
| Code | Category |
|---|---|
| W001 | Non-static ExecuteTemplate name |
| W002 | Unused template |
| W003 | Unguarded pointer dereference |
| W004 | Interface field access |
| W005 | Unused variable |
| W006 | Dead conditional branch |
| W007 | Inconsistent sub-template types |
These are type errors that check-templates reports regardless of the -w flag:
Accessing a field that does not exist on the data type.
type Page struct { Title string }Error:
{{.Titel}} {{/* typo — "Titel" does not exist on Page */}}
When {{template "name" .}} passes a type that doesn't match what the sub-template expects.
{{printf "%d" .Name}} where .Name is a string produces a type error. The tool validates that format verbs (%d, %s, %f, etc.) match the types of the corresponding arguments. %v accepts any type.
The vscode-go-template-check directory contains a VS Code extension that shows diagnostics inside template files (.gohtml, .tmpl, .gotmpl) — not just at Go call sites.
Features:
- Red squiggles on
{{.MissingField}}in template files - Yellow squiggles for warnings (W001–W007)
- Syntax highlighting for Go template directives in
.gohtmlfiles - Runs automatically on save
The extension requires the check-templates binary on your PATH. See the extension README for setup and configuration.
Call Execute with a types.Type for the template's data (.) and the template's parse.Tree. See example_test.go for a working example.
muxt— builds on this library to type-check templates wired to HTTP handlers. If you only need command-line checks,muxt checkworks too.- jba/templatecheck — a more mature alternative for template type-checking.
- You must provide a
types.Typefor the template's root context (.). - No support for third-party template packages (e.g. safehtml).
- Cannot detect runtime conditions such as out-of-range indexes or errors from boxed types.
- Template initialization generally requires static arguments, but the tool can trace
embed.FSvariables through function parameters across packages and resolvefs.Globpatterns against embedded file lists. Dynamically constructed file lists that cannot be statically resolved are skipped gracefully.