Skip to content

Best Practices and Common Patterns

Knowing the features of VIBE is the first step. Using them effectively is the next. Here are some best practices and patterns to help you build clean, robust, and maintainable templates.

If you want more copy-pasteable examples, see Common Recipes.

1. Component vs. Definition: When to Use Which?

This is the most important architectural decision you'll make.

  • Use a definition when: You are defining a data structure—a standard set of fields that belong together. Think of it as a "data contract."
    • Good examples: person, address, company, indemnity_properties.
  • Use a component when: You are creating a reusable piece of presentation—a chunk of .md or .docx content. Think of it as a "document building block."
    • Good examples: signature_block, confidentiality_clause, title_page.

The best practice is to have your presentation-focused components declare which data definition they use.

2. Keep Logic Out of the Template

Your document template (.md or .docx) should be as "dumb" as possible. It should focus on layout and printing variables, not complex calculations.

  • Instead of this (in template.md):

    Total: ${{ (base_price * (1 + tax_rate / 100)) * (1 - discount_rate / 100) }}

  • Do this (in config.yml):

    total_price:
  type: computable
  compute: (base_price * (1 + tax_rate / 100)) * (1 - discount_rate / 100)

    And this (in template.md):

    Total: ${{ total_price }}

    This makes your logic explicit, testable, and reusable.

3. Name Your Variables Clearly

Use descriptive, clear variable IDs.

  • Instead of: p_name, val, b
  • Prefer: project_name, contract_value, is_subsidiary

This makes both your config.yml and your templates much easier to read and understand months later.

4. Start Simple and Refactor

You don't need to design the perfect system from the start.

  1. Begin by writing out the text in a single component.
  2. As you identify variables, add them to the component's inputs.
  3. If you find you're reusing the same set of inputs across multiple components, refactor them into a shared definition. This "start small, grow big" approach is much more manageable than trying to design everything upfront.

5. Use | or for a Better Preview Experience

Use the | or filter (or its locale alias, e.g. | eller in Swedish) on variables that might not have an answer yet. It renders a visually distinct placeholder — bracketed and highlighted in the web preview, bracketed in DOCX — so readers can immediately spot gaps.

This agreement is made on {{ effective_date | or('effective date') }}.

For Swedish templates:

Avtalet ingås den {{ avtalsdatum | eller('avtalsdatum') }}.

Avoid | safe_default for this purpose — it returns plain text without placeholder styling, making gaps harder to spot. Reserve safe_default for cases where you need a raw text substitution without any markup, such as inside expressions or conditionals.