Flext

Flext is a technology for building reliable document templates.

In many systems, templates start simple and gradually become fragile: fields appear without documentation, rendering logic spreads across multiple layers, versions break compatibility, and debugging becomes difficult. Flext addresses this problem by allowing templates to describe the structure and requirements of the document itself.

A Flext template can contain Markup, Metadata, Modules, and rendering hints in a single artifact. This makes templates easier to reuse, validate, and embed into larger systems such as document pipelines, reporting services, or contract generation platforms.

• GitHub: TrustMe-kz/flext
• NPM: @trustme24/flext
• Demo: Available at CodeSandbox
• Documentation: Available at TrustMe Wiki

Installation

npm i @trustme24/flext tailwindcss

Add the CSS import:

@import "@trustme24/flext/index.css";

🎉 That's It!

The Problem

Document templating often looks simple at first. Over time it tends to accumulate hidden complexity.

Typical issues include: undocumented fields, incompatible template versions, duplicated rendering logic across services, fragile helper usage, and weak validation before rendering.

A few common scenarios illustrate the problem:

1. A template expects a field that is not provided at runtime. The result is either a broken document or silent incorrect output.
   Solution with Flext: The template can explicitly declare required fields using Metadata so missing data is detected early.

————————————

2. Multiple services use the same template but apply different helper logic or formatting rules.
   Solution with Flext: Templates can declare Module dependencies so rendering logic is predictable and consistent.

————————————

3. Templates evolve but older documents still rely on previous versions.
   Solution with Flext: Templates can carry explicit Version information and compatibility rules.

What It Provides

Flext builds on top of Handlebars and keeps its familiar syntax while adding a small metadata layer. The goal is not to replace existing template engines but to make document templates safer and easier to maintain.

Instead of treating templates as plain text files, Flext treats them as structured artifacts. A template can include Markup, Metadata directives, and Module dependencies, all stored together.

This approach helps systems understand what a template requires before rendering it.

Quick Start:

import Flext from '@trustme24/flext';

const template = `
  {{!-- @syntax "1.0" --}}
  {{!-- @use "put" --}}
  <p>{{ put name 'Unknown user...' }}</p>
`;

const flext = new Flext(template, { name: 'Anna' });

document.body.innerHTML = flext.html;

Core Ideas

A Flext template contains three conceptual layers. The first layer is markup: HTML and standard Handlebars expressions. The second layer is Metadata written as directives such as @v, @field, or @use. The third layer is runtime behavior provided through Modules and helpers.

Keeping these elements close together makes templates easier to move between systems and reduces hidden assumptions.

Metadata directives can describe template Version, language, title, rendering parameters, and required fields. Modules provide reusable logic such as formatting numbers, inserting fallback values, or conditional rendering.

Example

import Flext from '@trustme24/flext';

const template = `
  {{!-- @syntax "1.0" --}}
  {{!-- @use "put" --}}
  {{!-- @group "data" --}}
  {{!-- @field "data.someField" type="string" label="Message" required --}}

  <p class="text-center text-red-500">
    {{ put data.someField 'No hello world...' }}
  </p>
`;

const flext = new Flext(template, {
  data: { someField: 'Hello World!' },
});

console.log(flext.html);   // <p class="...">Hello World!</p>
console.log(flext.model);  // {"name":"data","$":[{"name":"someField"}]}

💡 In this example the template carries additional information: Version, Field definition, and Module usage. This allows runtime tools to build a Data Model, validate input, and render HTML predictably.

Use Cases

Flext is intended for structured document generation. Common examples include contracts, invoices, reports, certificates, and internal document workflows. It is particularly useful when templates must be versioned, validated, reused across services, or rendered in multiple environments.

Flext can be used on its own, but it is also designed to serve as a core library inside larger systems. Related tools include vue-flext for Vue integration, flext2pdf for HTML‑to‑PDF rendering, and some Flext Convert Service for running document rendering as a microservice.

Together these components allow Flext to power full document pipelines while remaining a lightweight core library.

Writing Templates

Templates should stay declarative and focused on layout. Business logic is usually better handled in Modules or application code. Metadata directives such as @field help document required data and make validation possible.

Example:

{{!-- @syntax "1.0" --}}
{{!-- @use "put" "date" --}}
{{!-- @group "data" --}
{{!-- @field "data.city" type="string" label="City" required --}}
{{!-- @field "data.date" type="date"   label="Date" required --}}

<p>
  {{ put data.city "City" }}, {{ put (date:text data.date "No date...") }}
</p>

Best practices

Treat templates as versioned artifacts. Prefer explicit metadata over hidden assumptions. Keep helper usage predictable and document important data paths with @field. Test templates with realistic data and separate document layout from application business rules.

Limitations

Flext is intentionally focused. It is not a full programming language, not a WYSIWYG editor, and not a complete document management system. Its role is to act as a reliable template core inside document generation workflows.

API

The main entry point is the Flext class.

Constructor:

import Flext from '@trustme24/flext';

new Flext().setTemplate('...').setData({});

More information about the API is available at TrustMe Wiki.

Architecture

Flext operates as a simple pipeline.

Template
  v
Parser / AST
  v
Directives / Modules
  v
PDF / Preview / Data Model / Export

At runtime Flext parses the template, extracts Metadata, registers Modules, builds a Data Model, and generates preview. The output can then be passed to other tools to display, store, or generating PDF.

• Repo: More information about the repo can be found in ARCHITECTURE.md
• Documentation: More information about the API is available at TrustMe Wiki

Development

npm run test:app

Run Tests:

npm run test

More information about the contribution can be found in CONTRIBUTING.md.

Roadmap

Future development focuses on improving reliability and adoption. Planned areas include stronger template validation, better parser and AST tooling, clearer compatibility rules, improved module authoring experience, richer documentation, ecosystem integrations, editor support, and a template corpus for regression testing.

• Contributions are welcome. Useful areas include documentation, example templates, modules, parser improvements, performance optimizations, and test coverage. Changes that affect the template syntax or core semantics should first be discussed in issues so architectural decisions remain consistent.

————————————

• Governance: Flext is maintained by TrustMe. External contributions are encouraged while core design decisions remain centralized to keep the language and runtime coherent.

————————————

• Security: If you discover a security issue, please report it privately to [email protected] instead of opening a public issue

————————————

• License: Flext is released under the MIT License

Flext by Kenny Romanov
TrustMe