# README
An HTML templating language for Go that has great developer tooling.
Documentation
See user documentation at https://templ.guide
Tasks
build
Build a local version.
go run ./get-version > .version
cd cmd/templ
go build
install-snapshot
Build and install current version.
# Remove templ from the non-standard ~/bin/templ path
# that this command previously used.
rm -f ~/bin/templ
# Clear LSP logs.
rm -f cmd/templ/lspcmd/*.txt
# Update version.
go run ./get-version > .version
# Install to $GOPATH/bin or $HOME/go/bin
cd cmd/templ && go install
build-snapshot
Use goreleaser to build the command line binary using goreleaser.
goreleaser build --snapshot --clean
generate
Run templ generate using local version.
go run ./cmd/templ generate -include-version=false
test
Run Go tests.
go run ./get-version > .version
go run ./cmd/templ generate -include-version=false
go test ./...
test-short
Run Go tests.
go run ./get-version > .version
go run ./cmd/templ generate -include-version=false
go test ./... -short
test-cover
Run Go tests.
# Create test profile directories.
mkdir -p coverage/fmt
mkdir -p coverage/generate
mkdir -p coverage/version
mkdir -p coverage/unit
# Build the test binary.
go build -cover -o ./coverage/templ-cover ./cmd/templ
# Run the covered generate command.
GOCOVERDIR=coverage/fmt ./coverage/templ-cover fmt .
GOCOVERDIR=coverage/generate ./coverage/templ-cover generate -include-version=false
GOCOVERDIR=coverage/version ./coverage/templ-cover version
# Run the unit tests.
go test -cover ./... -coverpkg ./... -args -test.gocoverdir="$PWD/coverage/unit"
# Display the combined percentage.
go tool covdata percent -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit
# Generate a text coverage profile for tooling to use.
go tool covdata textfmt -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit -o coverage.out
# Print total
go tool cover -func coverage.out | grep total
test-cover-watch
gotestsum --watch -- -coverprofile=coverage.out
test-fuzz
./parser/v2/fuzz.sh
./parser/v2/goexpression/fuzz.sh
benchmark
Run benchmarks.
go run ./cmd/templ generate -include-version=false && go test ./... -bench=. -benchmem
fmt
Format all Go and templ code.
gofmt -s -w .
go run ./cmd/templ fmt .
lint
Run the lint operations that are run as part of the CI.
golangci-lint run --verbose
ensure-generated
Ensure that templ files have been generated with the local version of templ, and that those files have been added to git.
Requires: generate
git diff --exit-code
push-release-tag
Push a semantic version number to GitHub to trigger the release process.
./push-tag.sh
docs-run
Run the development server.
Directory: docs
npm run start
docs-build
Build production docs site.
Directory: docs
npm run build
# Functions
Bool attribute value.
Class returns a CSS class name.
Classes for CSS.
CSSID calculates an ID.
EscapeString escapes HTML text within templates.
Flush flushes the output buffer after all its child components have been rendered.
FromGoHTML creates a templ Component from a Go html/template template.
GetChildren from the context.
GetNonce returns the CSP nonce value set with WithNonce, or an empty string if none has been set.
Handler creates a http.Handler that renders the template.
InitializeContext initializes context used to store internal state used during rendering.
Join returns a single `templ.Component` that will render provided components in order.
JoinStringErrs joins an optional list of errors.
JSFuncCall calls a JavaScript function with the given arguments.
JSONScript renders a JSON object inside a script element.
JSONString returns a JSON encoded string of v.
JSUnsafeFuncCall calls arbitrary JavaScript in the js parameter.
KV creates a new key/value pair from the input key and value.
NewCSSHandler creates a handler that serves a stylesheet containing the CSS of the classes passed in.
NewCSSMiddleware creates HTTP middleware that renders a global stylesheet of ComponentCSSClass CSS if the request path matches, or updates the HTTP context to ensure that any handlers that use templ.Components skip rendering <style> elements for classes that are included in the global stylesheet.
NewOnceHandle creates a OnceHandle used to ensure that the children of its `Once` method are only rendered once per context.
Raw renders the input HTML to the output without applying HTML escaping.
RenderCSSItems renders the CSS to the writer, if the items haven't already been rendered.
RenderScriptItems renders a <script> element, if the script has not already been rendered.
SafeClass bypasses CSS class name validation.
SafeScript encodes unknown parameters for safety for inside HTML attributes.
SafeScript encodes unknown parameters for safety for inline scripts.
SanitizeCSS sanitizes CSS properties to ensure that they are safe.
ToGoHTML renders the component to a Go html/template template.HTML string.
URL sanitizes the input string s and returns a SafeURL.
WithOnceComponent sets the component to be rendered once per context.
WithContentType sets the Content-Type header returned by the ComponentHandler.
WithErrorHandler sets the error handler used if rendering fails.
WithNonce sets a CSP nonce on the context and returns it.
WithStatus sets the HTTP status code returned by the ComponentHandler.
WithStreaming sets the ComponentHandler to stream the response instead of buffering it.
WriteWatchModeString is used when rendering templates in development mode.
# Constants
FailedSanitizationURL is returned if a URL fails sanitization checks.
# Variables
NopComponent is a component that doesn't render anything.
# Structs
ComponentCSSClass is a templ.CSS.
ComponentHandler is a http.Handler that renders components.
ComponentScript is a templ Script template.
CSSHandler is a HTTP handler that serves CSS.
CSSMiddleware renders a global stylesheet.
Error returned during template rendering.
KeyValue is a key and value pair.
OnceHandle is used to ensure that the children of its `Once` method are are only rendered once per context.
# Type aliases
Attributes is an alias to map[string]any made for spread attributes.
ComponentFunc converts a function that matches the Component interface's Render method into a Component.
ConstantCSSClass is a string constant of a CSS class name.
CSSClasses is a slice of CSS classes.
JSExpression represents a JavaScript expression intended for use as an argument for script templates.
SafeCSS is CSS that has been sanitized.
SafeURL is a URL that has been sanitized.