cargo-telar 0.2.2

Cargo subcommand for Telar apps: dev server with hot reload, and packaging into native installers.
cargo-telar-0.2.2 is not a library.

Telar

CI crates.io docs.rs license

A modular Rust UI framework with its own template language, reactive signals and a self-contained renderer.

Telar draws every pixel itself — there is no webview and no native widget toolkit underneath. Components are written in .rsx, an indentation-based template language that compiles to plain Rust at build time, so what ships is a single binary with no runtime interpreter.

Early days. Telar is at 0.2.2. The APIs work and are exercised by the apps in this repo, but they will keep moving before 1.0.

A component

[logic]
#[derive(Default)]
pub struct Props {
    pub icon: &'static str,
    pub title: &'static str,
    pub body: &'static str,
}

[view]
box fill:$theme.surface stroke:$theme.border radius:16 width:300 pad:24 gap:10 axis:col
    text "{props.icon}" font_size:32
    text "{props.title}" font_size:18 color:$theme.dark
    text "{props.body}" font_size:14 color:$theme.muted

[preview "Fast"]
feature_card icon:"⚡" title:"Fast" body:"Software and wgpu renderers with dirty tracking."

A .rsx file has up to four sections: [logic] for verbatim Rust (a pub struct Props declares the component's props), [style] for reusable style classes, [view] for the node tree, and [preview] blocks that the tooling renders in isolation, with live controls, a [play] that drives them and snapshots that guard them (docs/previews.md).

[logic] is Rust at two levels. An item written at its left margin — use, const, static, fn, struct, enum, impl, trait, type, mod, macro_rules! — is an item of the file's module, so a [style] class, a [preview], a #[cfg(test)] mod tests and another module can name it. A statement — a let, an effect(…) — runs in the component each time it is built, where props is in scope.

Quick start

cargo install cargo-telar
cargo telar new my-app        # --target desktop | tui | web | android
cd my-app
cargo telar dev

That is the whole of the setup. cargo telar new writes the manifest, the build profiles, a theme, an app root and one .rsx component, with one target already named — there is nothing to wire up and no feature list to read first.

Already have a directory — a fresh git init, a Nix flake, a README you wrote first? cargo telar init writes the same files into it in place. It never overwrites anything: a name it would itself write that already exists is a conflict, and it refuses the whole write and lists every one rather than touching any of them (an existing Cargo.toml included — merge one by hand, or start from an empty directory instead).

cargo telar init            # scaffolds the current directory
cargo telar init my-app     # or a path, same as `new`
cargo telar init --target web --renderer dom   # dom | canvas | auto, browser only
my-app/
  Cargo.toml      # one target under [features], the widget catalogue, and the build profiles
  telar.toml      # renderer backend, the components .rsx sees, theme, catalogs, the dev window
  src/main.rs     # fn main() { my_app::run(); }
  src/lib.rs      # telar::app!(…) — theme, startup hook, config, root
  src/theme.rs    # the design tokens every component reads
  src/app.rs      # the root component
  src/home.rsx    # one page

src/lib.rs is the whole of the wiring:

telar::app!(
    theme::AppTheme,
    { telar::set_theme(theme::AppTheme::light()); },
    telar::AppConfig::default(),
    app::Root
);

and telar.toml sits next to Cargo.toml:

[telar]
backend = "auto"
prelude = ["telar_components"]

[telar.dev.window]
title = "my-app"
width = 1000
height = 700

Then:

cargo telar dev        # run with hot reload
cargo telar preview    # open the component workshop on every [preview], hot-reloaded
cargo telar preview <ID>         # open the workshop on one preview, or move the open one there
cargo telar preview --png out/   # render each one, and each matrix cell, to a PNG instead, with no window
cargo telar test       # build, play, a11y-check and snapshot every preview and matrix cell, headlessly
cargo telar test --update-snapshots   # write the goldens under previews/__snapshots__ that are missing or changed
cargo telar check      # type-check, with .rsx errors on the lines you wrote
cargo telar build --format deb   # appimage | deb | dmg | nsis | apk | dir
cargo telar doctor     # check the toolchain

One target, one word

Telar is a set of small crates behind one facade, and a build carries the target it named and nothing else:

Your app runs in default = [...] Crates compiled
A desktop window (Linux, macOS, Windows) ["desktop"] 397
The terminal it was launched from ["tui"] 102
A browser, drawing as a document ["web-dom"] 77
A browser, document and WebGPU canvas ["web"] 210
Android ["android"] 299
Nothing — draw commands in, pixels out ["headless"] 174

Counted with cargo tree -p telar --no-default-features --features "<target>" -e normal --target all, so every platform's dependencies are in the figure at once. Every row is complete on its own: naming it is the whole of the choice, and no row pays for another — a desktop build is mostly wgpu and its shader toolchain, and a terminal build links neither. Switching later is one word in Cargo.toml.

Per-target guides, and how to ship two targets from one codebase, are in docs/targets.md.

One value grammar

An attribute is key — a flag that asserts itself — or key:<rust expression>, read to the next space at delimiter depth 0. Every value is Rust, evaluated in the generated scope, so a call, a path, a method chain, a macro or a closure is itself and rustc judges it against the line you wrote:

col gap:8 pad:(space::lg() * 2.0) align:center
    btn "Save" on_press:(|| draft.save()) fill:$theme.primary
    text "Hola {name}" font_size:14

A quoted value is text, as a text's content is: {expr} interpolates and {{/}} is a brace, whether it is the content, a label: or a component's prop (button label:"Open {name}"). A closure that formats it borrows what it reads, and copies in a [logic] binding — or the field of props it reads — that another part of the view still needs, so text "{props.detail}" and text "{project()}" need no re-binding first. What an if let or a match arm binds is copied into the closures under it, so if let Some(place) = &location can be read by a text below.

Parenthesise an expression that holds a space — (a + b) is an expression, so nothing new is invented. Four sugars survive, because each is a token shape rather than a second language:

written means
50% SizeDimension::Percent(0.5)
50sw 50sh 50smin 50smax a fraction of the surface: SizeDimension::SurfaceWidth(0.5) and its siblings — see docs/surface-size.md
#3d78fa Color::rgba(…)
$sig sig.get() — a read of anything reactive, including the theme handle the view binds

key(…) is reserved for the handful of directives that have a grammar of their own and are not Rust at all: transition(fill 250ms ease-out) is a clause list, hover_style(fill:$theme.accent) a nested attribute list. The spelling says which world you are in.

Reactivity is reading, not marking. A layout value that can change is re-resolved whenever what it reads changes — pad:$theme.gutter follows a theme switch, and so does pad:gutter(). One that cannot — a literal, or arithmetic on constants spelled as constants are, gap:(GRID * 2.0) — costs nothing to keep. A component's prop follows what it reads the same way: a $ read, a use_…() hook read through (color:(use_workbench_tokens().accent)) or a signal's .get() hands the prop a Reactive that re-reads it, and a plain value, or a hook's handle passed on, is handed over as it is. The $ is .get() sugar; it does not decide anything.

Components are Rust paths

A .rsx file is a module, and its component is the pub fn named after the file. Import what you call:

[logic]
use crate::ui::card::{card, CardProps};

[view]
card pad:20
    text "inside" font_size:14

Every .rsx already sees telar's items and your crate root's. Components that ship in a crate of their own are made visible the same way by naming that crate once, in telar.toml:

[telar]
prelude = ["telar-components"]   # a package name, or a path inside one: "my_plugin::prelude"

Each entry is glob-imported after telar's glob and before your crate's, so it has to be a dependency of the package. An explicit use in [logic] shadows every glob, which is how one file picks a name two crates both export. A workspace telar.toml can declare the list for every package; a package that sets its own, [] included, replaces it.

A directory is a module too, and mod.rsx is that module's file — mod.rs in the other language. Its [logic] is Rust at module level, which is where a //! and a #![…] belong; it takes no [view], because a module is not callable. Give a directory one and telar declares it and everything under it, so nothing in it has to be placed by hand:

src/media/
  mod.rsx         # the module: docs, attributes, and Rust items
  mod.rs          # optional, and kept as it is: included into the same module
  media.rsx       # crate::media::media
  state.rs        # crate::media::state

Without a mod.rsx, a directory that holds both .rsx files and a hand-written mod.rs places them from that file with a telar::rsx_modules!(); of its own — only a module's own file can add items to it.

A module written as keymap.rs beside keymap/ cannot place the .rsx in keymap/: the macro reaches its declarations through an include! resolved beside the file that invokes it, which for keymap.rs is its parent's directory, and a proc macro cannot tell which file it was written in under rust-analyzer. The build names every such .rsx instead of leaving it out; move keymap.rs to keymap/mod.rs, or give the directory a mod.rsx.

apps/sandbox in this repo is the reference app and covers most of the surface.

Shared classes

A class is the file's own until it says otherwise. pub @name shares it, and a use in another file's [style] brings it in by its module path, Rust's own spelling with class names where Rust has items:

[style]
pub @mono
    font_family: telar_devtools::use_workbench_tokens().mono_family
    font_size: telar_devtools::use_workbench_tokens().mono_size
[style]
use crate::styles::{mono, line as rule};
use super::cards::*;

[view]
row @rule align:center
    text @mono "{seq}"

A .rsx with classes and no [view] — src/styles.rsx above — is a module of them rather than a component, and a directory's mod.rsx may hold the classes its modules share. A class is a bundle of attributes written onto each element that names it, so its values are Rust read where it is used, the way a macro_rules! macro's paths are: a shared class names what it reads by a path any file can reach, or each file that uses it imports that name. A class no [style] declares or imports is an error on the element naming it, and so is an import of a module that is not there, of a class it does not declare, or of one it keeps private.

What's in the box

Everything here is either always present or one word away. Nothing is bundled.

  • Reactive signals — a fine-grained graph of signals, memos and effects; no virtual DOM, no diffing.
  • Flexbox and grid layout on top of Taffy, with reactive writing direction (LTR/RTL), lengths relative to the surface, and width breakpoints that re-resolve only across a threshold. → docs/surface-size.md
  • Sticky positioning — sticky inset_top:0 holds a box at a scroll viewport's edge inside its parent, placed by Telar on every target and by native position: sticky on web-dom. sticky:$on and clip:$on switch it, or a clip, by state without a rebuild. → docs/sticky.md
  • Primary scroll — a root ScrollPage is the page's own scroll: the document's scroll on web-dom, a drawn scroll area elsewhere, readable and movable by platform code. use_primary_scroll() reads it reactively from anywhere, and use_anchor_at(line) the anchor under a line of its view. Its arrival margin, taken from the bars of the layers fixed over it or declared, keeps an anchor followed or a control focused clear of them (scroll-padding on web-dom). → docs/primary-scroll.md
  • Fixed layer — layer stands boxes against the surface over the page: out of its flow and its scroll, drawn over its sticky boxes and under every overlay, taking the pointer only over its own boxes and keeping its place in the Tab order. position: fixed in place on web-dom, a layout root of its own elsewhere. → docs/fixed-layer.md
  • Motion — tweens and springs driven by one frame ticker, with colors interpolated in Oklch.
  • Theming — theme tokens plus light/dark mode, reduced motion and high contrast that can follow the OS, and the user's preferred locales, read the same way on every target. → docs/system-preferences.md
  • Keyboard — each focusable control declares the keys it keeps, so a browser build shares Tab and scrolling with the host page instead of fighting it for them. → docs/keyboard.md
  • Internationalization — translation catalogs baked at build time; t! validates keys and arguments at compile time. Full CLDR plural rules and locale-aware number and date formatting are in the plugin telar-i18n.
  • Two renderers — a CPU rasterizer on tiny-skia and a GPU one on wgpu, behind the same drawing vocabulary. desktop and android bring both, and backend = "auto" picks per machine.
  • A widget catalogue — buttons, fields, selects, menus, modals, tabs, sliders, and the rest — in the plugin telar-components: add it with the groups you draw (overlays, chrome, advanced) and list it as a prelude in telar.toml. → docs/targets.md
  • Navigation — a reactive page stack with animated transitions, or one stack per tab, that follows the app's address — in the plugin telar-navigate: add it and list it as a prelude in telar.toml. → docs/targets.md
  • Location — one address per app on every target: browser history with scroll restoration, --location deep links remembered between runs, Android ACTION_VIEW and the back button. → docs/location.md
  • Surface title — the window, tab, recents label or terminal title is derived from the app's title, the current route's title and the locale, and follows all three. → docs/surface-title.md
  • Links — to: makes a box a link to a route, an anchor on the page or a URI outside the app: a real <a href> on web-dom, open_uri through the system everywhere else, OSC 8 in a terminal. current: marks the current one (aria-current). → docs/links.md
  • Dashed strokes — stroke_dash:"1 4" on a path, or Stroke::with_dash in a canvas, dashes an outline on every renderer: SVG stroke-dasharray on web-dom, tiny-skia's own dashing on the CPU, dashes cut before tessellation on the GPU, dashed line characters in a terminal. → docs/dashed-strokes.md
  • Images and SVG — baked into the binary at build time out of src:"…", with no parser in the binary. → svg
  • Icons — icon name:"mdi:home", or name:"home" with a default set, draws an Iconify icon: a monochrome one in the colour of the text around it, a palette one in its own colours. Icons are baked at build time from Iconify sets on disk, your own SVGs or a provider you name, with each set's licence recorded in a notice — in the plugin telar-icons.
  • Translation catalogs baked the same way, with t! validating keys and arguments at compile time.

Both are baked by the CLI, and so is the .rsx itself: build through cargo telar check/dev/build/test, or run cargo telar transpile first. A plain cargo build fails with a message naming that command rather than compiling something stale, which is what keeps the decoders, the parser and the code generator out of every project's own build. A project that will not install the CLI produces the artifact itself from a build.rs, which is one call into telar-transpiler and gets real cargo:rerun-if-changed out of it.

  • Assets that arrive later, behind a transport-agnostic reactive seam: a signal that advances Loading → Ready/Failed, with the transport, the cache and the decoder each yours to choose. → async-assets
  • Decoders and transports for that seam — SVG, bitmaps, translation catalogs, over HTTP or from a directory — in the companion crate telar-dynamic, one feature each. Yours plugs in the same way.
  • Hot reload in cargo telar dev, and an in-app devtools overlay for inspecting the live component tree — the plugin telar-devtools, an optional dependency cargo telar new declares and cargo telar dev turns on — or one of your own, through the same seam. (the CLI sets this one)
  • Previews and a component workshop: write a component in a state once, as a [preview] in .rsx or preview! in Rust, and see it in the workshop with live controls, across themes, languages and sizes, play it, check it for accessibility, and snapshot it. → cargo telar preview, cargo telar test (docs/previews.md)
  • Packaging to native installers per platform, plus Android APKs. → cargo telar build --format … For the browser, a static site from a page template with content-hashed assets, an asset-manifest.json and a verbatim web/public/ → cargo telar build --target web, configured under [telar.web] (docs/web-packaging.md). With --prerender, every page and locale written ahead of time, readable before the module loads and naming each element for the client that takes it over → docs/prerender.md. Each page carries its description, canonical, alternate-language and link-preview tags, derived from [telar.web], the catalogs and the routes, with a sitemap.xml, a root that negotiates the reader's locale, and host profiles (static, cloudflare-pages) for the files a host reads beside the site.

The complete list, with what each feature pulls in and why, is on docs.rs.

Editor support

The VS Code extension provides syntax highlighting, snippets, diagnostics, completion and component preview, backed by the telar-analyzer language server. A component's attribute keys are completed from its props struct — names, types and doc comments — through an embedded rust-analyzer, and a diagnostic about a value lands on the .rsx line and column you wrote it on. The extension bundles a prebuilt server binary, so no extra install step is needed.

Build tuning

cargo telar new writes profiles that keep dev builds fast and release builds small. Adding Telar to an existing workspace, wanting a faster linker, or wanting to know why panic = "abort" must stay off [profile.dev]/[profile.release] but is fine in [profile.web]: see docs/build-tuning.md.

Crates

You depend on one:

[dependencies]
telar = "0.2.2"

Everything behind it — the reactive graph, the layout engine, the renderers, the platform backends, the .rsx pipeline — is a separate telar-* crate. They are published because Cargo requires every dependency of a published crate to be published too, not because an application names them; the split is what lets a terminal build skip a GPU renderer. Reach for one directly only if you are writing a frontend or a tool against Telar's internals.

Two exceptions. cargo-telar is a binary you install rather than a dependency. telar-embed is for hosting a separately-compiled Telar UI inside your own — or for being one. The rest is opt-in, and it is a plugin.

Plugins

telar is the mechanism: traits, protocols and registries. The batteries an application may want are plugins, crates you add to your own Cargo.toml beside the facade, which carries none of them:

Plugin What it adds
telar-components The widget catalogue. No default features; groups overlays, chrome and advanced
telar-navigate The page stack: Navigator, the host that animates between pages, per-tab stacks
telar-watch Filesystem watching delivered on the UI thread: watch_path
telar-dynamic Decoders and transports for assets that arrive at run time, one feature each
telar-icons The icon tag for Iconify set:name ids, baked from local sets, your own SVGs or a provider you name, with each set's licence recorded; feature runtime resolves ids as the app runs
telar-i18n CLDR plural rules for catalogs, and number and date formatting in the active locale, from ICU4X
telar-expression A typed, pure expression language bound to signals
telar-devtools The dev overlay: FPS counter, node inspector, build-error banner — an optional dependency cargo telar dev turns on, so no shipping build compiles it
telar-workshop The component workshop cargo telar preview opens: a sidebar of every preview, a canvas of its own for each, live controls, a matrix view and the panels that review a play and a snapshot — an optional dependency cargo telar preview turns on, so no shipping build compiles it

The layout rule. plugins/ holds every crate built on top of the facade, including what the tooling adds on its own, such as the devtools overlay cargo telar dev turns on and the workshop cargo telar preview opens. crates/ holds telar, the kernel crates behind it and host-side tooling (crates/tools/); a crate a telar feature pulls in and compiles into the target is core, even when it is opt-in. Nothing under crates/ depends on plugins/, which .github/scripts/check-layering.sh enforces in CI.

Adding one. Add the crate, name the feature groups you draw, and, for a plugin that ships .rsx tags, list it in telar.toml so every .rsx file sees them without a use:

cargo add telar-components --features overlays
cargo add telar-navigate
# telar.toml
[telar]
prelude = ["telar_components", "telar_navigate"]

Keep every plugin on the same version as telar: two copies of the kernel resolve to incompatible types. A tag missing from every prelude, an unknown crate and a name two entries both export are each reported on the telar.toml or .rsx line that caused them.

Writing one. A plugin is a Rust crate that depends on telar and follows the component protocol, or a [telar] library written in .rsx and published with cargo telar package and cargo telar publish. Both are covered in docs/plugins.md.

Crate Purpose
telar-reactive-core Signals, memos, effects, batching
telar-geometry-core Points, rects, transforms, border radii, Oklch color
telar-layout-core · telar-layout-reactive Flexbox/grid engine and its reactive context
telar-motion-core Tweens, springs, the frame ticker
telar-theme-core Theme tokens, light/dark mode
telar-semantics-core What a thing in an interface is, for screen readers, documents and terminals
telar-ui-core · telar-ui-tree Widget kernel, component tree
telar-renderer-core Draw commands, culling, dirty tracking
telar-renderer-software · telar-renderer-hardware CPU and wgpu backends
telar-renderer-tui · telar-renderer-dom · telar-renderer-web Terminal cells, browser elements, browser canvas
telar-renderer-text · telar-renderer-assets Text shaping and glyph atlas; SVG parsing and build-time asset baking
telar-embed Embedding a separately-compiled UI, or being one — a crate an application depends on directly
telar-renderer-cache · telar-renderer-record The shared byte-budgeted cache; a backend that records instead of drawing
telar-wire-core The byte spelling of what crosses between a host and a guest library
telar-platform-core and telar-platform-{winit,desktop,android,tui,web,headless} Window/event abstraction and its backends
telar-preferences-core The user's system preferences as reactive state, which theme, motion and plugins follow
telar-parser · telar-transpiler · telar-macros The .rsx pipeline
telar-project What a project is: telar.toml, source discovery, output paths, and the build artifacts a transpile leaves behind
telar-i18n-core · telar-services-core i18n runtime, platform paths and DI
telar-reactive-local Per-surface thread-local slots, split out so platform-core need not link the reactive runtime
telar-icons-core Iconify ids, sets, sources and licence policy, shared by telar-icons and the baker

The plugins are in the table above; plugins/telar-rsx-fixture is an unpublished test fixture, a [telar] library the test suite packages, unpacks read-only and compiles as a dependency.

telar-analyzer and telar-diagnostics live in this repo but are distributed through GitHub Releases and the VS Code extension rather than crates.io.

Minimum supported Rust version

Rust 1.95. Bumping it is a minor-version change.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.