Claude Code for Go Templ — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are building Go web applications with Templ, a type-safe HTML templating language for Go. Templ provides a JSX-like syntax that compiles to Go code, giving you compile-time type checking, IDE autocomplete, and component composition. Claude Code can write Go templates, but it generates html/template stdlib code instead of Templ’s component-based approach.

What Claude Code Gets Wrong By Default

  1. Uses Go’s html/template package. Claude writes Go template syntax like double-brace dot-Title with template.ParseFiles(). Templ uses a JSX-like syntax in .templ files that compiles to type-safe Go functions.

  2. Passes data through interface{} maps. Claude creates map[string]interface{} for template data. Templ components are Go functions with typed parameters — templ Page(title string, items []Item) gives compile-time type checking.

  3. Separates templates from handlers. Claude puts templates in a templates/ directory loaded at runtime. Templ components are compiled into Go code — they live alongside your Go code and are checked at compile time.

  4. Ignores component composition. Claude creates monolithic templates with Go’s template-include syntax. Templ supports proper component composition — @Header() calls inside templ Page() for nested, reusable components.

The CLAUDE.md Configuration

# Go Templ Project

## Templating
- Language: Templ (type-safe Go HTML templates)
- Files: .templ files compiled to Go
- Syntax: JSX-like with Go expressions
- Build: templ generate compiles .templ to .go

## Templ Rules
- Components: templ ComponentName(params) { ... }
- HTML: standard HTML elements in templ body
- Go expressions: { variable } for interpolation
- Composition: @ChildComponent(args) for nesting
- Conditionals: if/else in templ body
- Loops: for _, item := range items { ... }
- CSS: css className() { property: value; }
- Script: script functionName() { ... }

## Conventions
- .templ files alongside .go files
- Run templ generate before go build
- Use templ generate --watch during development
- Components as functions with typed parameters
- Handler: templ.Handler(component) for http.Handler
- Render: component.Render(ctx, w) for manual rendering
- HTMX: pair with HTMX for interactive pages

Workflow Example

You want to create a web page with reusable components. Prompt Claude Code:

“Create a Go Templ web app with a layout component, a navigation bar, and a product listing page. Each product card should be a separate component receiving typed product data. Set up the HTTP handler that renders the page.”

Claude Code should create layout.templ with a templ Layout(title string) component, nav.templ with templ Nav(activeRoute string), product.templ with templ ProductCard(p Product) and templ ProductList(products []Product), compose them with @Layout("Products") { @Nav("/products") @ProductList(products) }, and create the HTTP handler using templ.Handler().

Common Pitfalls

  1. Forgetting to run templ generate. Claude edits .templ files but the changes do not appear. Templ files must be compiled to Go code with templ generate before building. Use templ generate --watch during development for automatic recompilation.

  2. Using Go template syntax in .templ files. Claude writes double-brace Go template expressions inside .templ files. Templ uses { title } without double braces — the syntax is different from Go’s html/template.

  3. Not installing the Templ VS Code extension. Claude writes .templ files without syntax support. Install the Templ VS Code extension for syntax highlighting, autocomplete, and error checking in .templ files.