Feature Flags

FrankenTUI uses Cargo features to keep the default build small and let consumers opt in to tracing, telemetry, visual FX, and GPU acceleration. All tracing and telemetry features are off by default — enabling them adds compile-time cost only when requested.

Enable features per-crate in your Cargo.toml:


[dependencies]
ftui-core    = { version = "*", features = ["tracing"] }
ftui-render  = { version = "*", features = ["tracing"] }
ftui-runtime = { version = "*", features = ["tracing", "telemetry"] }

`ftui-core`

Feature	What It Enables	Default
`tracing`	Structured spans for terminal lifecycle	Off
`tracing-json`	JSON output via `tracing-subscriber`	Off

ftui-core::tracing emits spans around terminal setup, teardown, input parsing, and capability probing. Pair with tracing-json to get newline- delimited JSON suitable for log aggregation. See /runtime/telemetry for integration patterns.

`ftui-render`

Feature	What It Enables	Default
`tracing`	Performance spans for diff/presenter	Off

ftui-render::tracing wraps the hot path with tracing spans so you can see per-frame diff cost, presenter byte counts, and flush timings without modifying the render pipeline. Overhead when the feature is off is zero — the calls compile away.

`ftui-runtime`

Feature	What It Enables	Default
`tracing`	Runtime loop instrumentation	Off
`telemetry`	OpenTelemetry export (OTLP)	Off

ftui-runtime::tracing instruments the Elm loop (update, view, subscription reconciliation, effect execution).

ftui-runtime::telemetry adds OTLP export. When the feature is off, telemetry code and dependencies are excluded. When the feature is on but env vars are unset, overhead is a single startup check. Configure the exporter via OTEL_EXPORTER_OTLP_ENDPOINT — see /reference/env-vars.

`ftui-extras`

Feature	What It Enables	Default
`visual-fx`	Core types + Backdrop widget + CPU helpers	Off
`visual-fx-metaballs`	Metaballs effect (depends on `visual-fx`)	Off
`visual-fx-plasma`	Plasma effect (depends on `visual-fx`)	Off
`canvas`	Canvas adapters for sub-cell Braille/block rendering	Off
`fx-gpu`	Optional GPU acceleration (strictly opt-in)	Off
`markdown`	Markdown renderer	Off

fx-gpu default backends: Vulkan, GLES, DX12. Metal is intentionally disabled to avoid the unmaintained paste dependency; macOS uses CPU FX unless a Metal-safe path is added. See /concepts/visual-fx for the composition model.

Visual FX can be expensive. They automatically degrade via FxQuality when the frame budget is tight — but you can also force quality with set_quality_override() for testing.

`ftui-widgets`

Feature	What It Enables	Default
`command-palette`	Bayesian command palette widget + evidence ledger	On
`virtualized`	Fenwick-tree virtualized list + conformal height bounds	On

`ftui-a11y` and `ftui-i18n`

Both crates expose a minimal feature surface — see their individual pages:

Interaction with Env Vars

Several features are gated at runtime in addition to compile time:

fx-gpu respects FTUI_FX_GPU_DISABLE=1 and FTUI_FX_GPU_FORCE_FAIL=1.
telemetry only exports when OTEL_EXPORTER_OTLP_ENDPOINT is set.
Tracing output is controlled by standard RUST_LOG filters.

See /reference/env-vars for the complete catalog.

How to Choose Features

Library users: start with zero features and add tracing only when you need instrumentation.
Application authors: enable tracing on ftui-runtime plus tracing-json on ftui-core for structured logs in production.
Observability users: add telemetry on ftui-runtime and configure OTEL env vars.
Demo and showcase builders: enable visual-fx, visual-fx-metaballs, visual-fx-plasma, and optionally fx-gpu.

Feature Flags

ftui-core

ftui-render

ftui-runtime

ftui-extras

ftui-widgets

ftui-a11y and ftui-i18n