Axonyx Runtime

Standalone Rust runtime workspace for Axonyx applications.

Axonyx Runtime provides the execution contract for Axonyx apps: environment loading, backend request types, .ax lowering support, generated handler contracts, and the runtime foundation for future fine-grained UI updates.

Crates

This workspace includes:

• axonyx-runtime - public runtime contract and execution layer
• axonyx-core - parser, lowering, query model, SQL draft compiler, and shared core types
• axonyx-macros - ergonomic procedural macros used by the core/runtime layer

Install

For generated Axonyx apps, prefer the crates.io package:

[dependencies]
axonyx-runtime = "0.1.12"

Use the Git dependency only when testing unreleased runtime work:

[dependencies]
axonyx-runtime = { git = "https://github.com/vladanPro/axonyx-runtime" }

Local Development

cargo test

Runtime Role

The runtime is intentionally separate from the site/design packages:

axonyx-runtime  = Rust execution contracts and runtime support
axonyx-core     = parser, lowering, query, SQL, and shared compiler-facing types
axonyx-ui       = Foundry CSS/assets/.ax UI components
axonyx-framework = CLIs and app scaffolding workflow

Generated apps should depend on axonyx-runtime; framework tooling can additionally use axonyx-core and axonyx-macros as needed.

0.1.0 Focus

The first 0.1.0 release aims to stabilize:

• runtime env loading with AX_PUBLIC_* and AX_SECRET_*
• direct and api data transport contracts
• backend query and mutation request types
• .ax backend lowering and generated runtime handler contracts
• stable seams for generated Axonyx apps to call into runtime code

Anything beyond that can continue to evolve behind new minor releases.

Environment Convention

Public values use AX_PUBLIC_* and may be exposed to rendered output when appropriate.

Secret values use AX_SECRET_* and should remain server/runtime-only.

Examples:

AX_PUBLIC_APP_NAME=Axonyx Site
AX_SECRET_DB_URL=postgres://...
AX_SECRET_DB_DIALECT=postgres
AX_SECRET_DB_TRANSPORT=direct

Data Transport Direction

The runtime keeps data access contracts transport-aware:

• direct is the default runtime mode for normal database connections
• api is an explicit mode for API-key-backed data providers
• query and mutation requests stay framework-shaped while adapters translate into concrete driver/provider behavior

Reactivity Direction

Axonyx should not become a virtual-DOM rerender framework.

The preferred UI runtime direction is fine-grained and compiler-assisted:

compile .ax
  -> static HTML with stable node ids
  -> dependency graph
  -> small runtime patcher

A signal should map to exact patch targets, not whole component rerenders.

Example dependency shape:

count -> [
  { node: copy_text_1, target: Text },
  { node: reset_button, target: Attribute("disabled") }
]

When count changes, the runtime should patch only those targets.

Preferred phrasing:

Axonyx does not rerender components by default.
Axonyx patches exact targets produced by the compiler.

Binding Model Direction

Axonyx should separate storage from binding:

global/state = storage model
hard/soft = binding model

• global means app-level state
• state means component/route/local scoped state
• hard/signal binding means live DOM binding through a stable signal identity
• soft/value binding means snapshot or event/app-flow logic

Use this mental model:

Soft = snapshot
Hard = live handle

Avoid promising "zero runtime". More accurate terms are:

• minimal runtime
• compiler-generated runtime
• no virtual DOM
• no component rerender by default

Links

• crates.io: https://crates.io/crates/axonyx-runtime
• GitHub: https://github.com/vladanPro/axonyx-runtime