Textwire
Fast and beautiful templating language for Go that can be used for embedding variables and expressions into any text, including HTML and XML

Textwire. A templating language for Go
Textwire is a simple yet powerful templating language for Go. It is designed to easily inject variables from Go code into a template file or just a regular string.
Read Official Documentation
Installation
go get codeberg.org/textwire/textwire/v5
Neovim and VSCode Support
If you use Neovim or VSCode as your primary editor, you can install the Neovim Plugin or VSCode Extension to get syntax highlighting and other features for Textwire.
Globals Usage
You can pass globals to Configure or NewTemplate function like this:
tpl, err = textwire.NewTemplate(&config.Config{
GlobalData: map[string]any{
"env": "development",
},
})
In template files you can use globals like this {{ global.env }}.
Project Overview
- Module:
codeberg.org/textwire/textwire/v5 - Template Extensions:
.tw - Architecture: Modular design with separate packages for lexer, parser, evaluator, AST, token, and object handling
- LSP Support: Full Language Server Protocol implementation for editor integration
- Precedence: All the precedence defined in
./pkg/parser/parser.go:20-70
Development Environment & Commands
Available Commands
All commands run inside a container. Pull the image once before using them:
make pull
make pull- Pull the checks container imagemake test- Run all testsmake fmt- Format Go codemake lint- Run lintermake repl- Start the REPLmake check- Combines commands like: test, fmt, lintmake- Defaults tomake check
Commands use podman-compose by default. To use Docker Compose instead, override OCI:
make check OCI='docker compose'
Project Architecture
Core Packages
pkg/lexer/- Tokenizes input strings into tokenspkg/parser/- Builds AST from token streampkg/evaluator/- Evaluates AST nodes to produce outputpkg/token/- Token definitions and utilitiespkg/ast/- Abstract Syntax Tree node definitionspkg/value/- Runtime object system
Support Packages
config/- Configuration managementpkg/fail/- Structured error handlingpkg/utils/- Utility functionspkg/lsp/- Language Server Protocol implementation
Entry Points
textwire.go- Main public APIpkg/repl/repl.go- Interactive REPL
Code Style & Conventions
Import Organization
- Group imports: standard library, third-party, local packages
- Local packages use
codeberg.org/textwire/textwire/v5/prefix - Keep imports sorted and remove unused imports
Formatting Requirements
- ALWAYS run
make checkbefore committing changes - For non-Go files, respect
.prettierrcconfiguration (tabWidth: 4, singleQuote: true)
Testing Guidelines
Test Coverage Requirements
- Add tests for ALL new functionality
- Maintain high test coverage across all packages
- Test both success and failure scenarios
- Include edge cases and error conditions
Test Organization
- Co-locate test files with source files (
parser_test.gowithparser.go) - Use
textwire/testdata/for template test data - Organize test data into
good/andbad/subdirectories - Use descriptive test names that explain what is being tested
Test Patterns
- Use helper functions for common test setup
- Use option structs for configurable test behavior
Test Data
- Store template examples in
textwire/testdata/ - Use
.twextension - Include both valid and invalid examples for testing
- Name test files descriptively (e.g.,
if-statements.tw)
LSP Integration Guidelines
Metadata Updates
When adding new features, update LSP metadata in lsp/metadata/en/:
- Add completion items for new directives
- Update function signatures
Completion Items
- Add completions for new directives (
@if,@for, etc.) - Include function parameter hints
- Provide snippet completions for complex structures
- Update context-aware completions
Development Workflow
Pre-Commit Checklist
- [ ] Run
make checkbefore commit - [ ] Update LSP metadata if adding new features
- [ ] Add tests for new functionality
Versioning
- Follow semantic versioning (currently v2.x.x)
- Update CHANGELOG.md for significant changes
- Use appropriate emoji categories in changelog
- Maintain compatibility within major version
Specific Implementation Notes
Error Message Style
Write clear, descriptive error messages:
- Include context about what went wrong
- Provide suggestions for fixing the issue
- Use consistent terminology
- Follow existing message patterns in fail/fail.go
License
The Textwire project is licensed under the MIT License
Thanks To
Thanks to Codeberg and Forgejo for hosting Textwire.