Best Practices

Template Organization

Use Subfolders

Organize templates by project or report type:

templates/
├── academy/
│   ├── enrolled-by-career.typ
│   └── students-by-condition.typ
└── hr/
    ├── employee-card.typ
    └── salary-report.typ

Metadata Files

Always include a JSON metadata file alongside templates:

{
  "title": "Employee Card",
  "description": "Individual employee summary card",
  "exampleData": {
    "name": "John Doe",
    "department": "Engineering",
    "role": "Senior Developer"
  }
}

Data Handling

Validate Data Early

#let data = json.decode(sys.inputs.at("data"))
#let title = data.at("title", default: "Untitled Report")
#let items = data.at("items", default: ())

Use Descriptive Variable Names

// Good
#let studentName = data.name
#let enrollmentDate = data.enrolledAt

// Avoid
#let n = data.name
#let d = data.date

Typst Performance

• Avoid deeply nested loops for large datasets
• Use #table for tabular data instead of manual alignment
• Precompute expensive operations outside loops
• Use #set rules for global styling instead of repeating styles

Design Consistency

• Define a color palette at the top of your template
• Use consistent font sizes for headings, body text, and captions
• Set margins and page size explicitly for predictable output
• Test with different data lengths to ensure layouts don't break

Error Handling

#if data == none {
  [No data provided]
} else {
  // Render template
}

Version Control

• Store templates in version control alongside your data
• Use meaningful commit messages for template changes
• Test templates after updating Typst versions