The .xu language
The block format every .xu source file is written in, and the eleven building blocks a project is made of.
A .xu file is a block file, not a JavaScript module. Each block is one concern, and the object
blocks (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) are parsed as
JSON5-style literals: unquoted keys, arrays and nested objects are all fine.
Eleven building blocks
The folder a source file sits in decides which kind of unit it compiles to. A good Xu app usually reads more clearly when each concern gets its own unit instead of one file doing everything.
App.xu is the one reserved file: it is always the root app and always compiles to program id
app. For a component file the id resolves in order from meta.id, then mount.id, then the
file's own basename. Every other unit type carries no <mount> block, so its id resolves from
meta.id, then the file's own basename. For the JSON5 resources the order is id, then _id, then
basename. Duplicate ids across a project are not allowed.
Blocks by unit type
App.xu never needs a <mount> block. An ordinary component only needs one when you want it
mounted directly into an HTML page rather than reached through <panel program="...">:
The template language
Inside <template>, a small set of friendly aliases compiles down to the runtime's own xu-*
markup.
A component, end to end
<script> compiles into a client-side mount module: the default export receives a context object
and may return a disposer function to run on unload. <style> blocks are collected into one served
component stylesheet.
Datasource format
Use the readable wrapper form inside <datasource lang="json5">. type is one of none, table,
array, json or csv.
A table datasource uses table, filter, sort, direction, realtime, limit, skip and
output. An array, JSON or CSV datasource uses source.field or source.url. For any datasource
key the wrapper form doesn't expose, drop to mode="raw" and write the field names the runtime
document itself uses.
The other ten blocks, briefly
Named, reusable reads. data/get/LoadStudentClasses.xu pairs <params> (declared in/out
fields) with a <datasource>, so a component calls a loader by name instead of owning query
details itself.
Named writes. data/set/SaveStudentProfile.xu adds crudMode and allowCreate to <meta>
alongside the params and datasource, giving persistence a visible, testable home in source.
Record-by-record processing. data/batch/RebuildClassRoster.xu runs an <events> step such as
before_record against every row the <datasource> resolves.
A <response> block turns params, datasource results and events into a JSON-style payload:
A named, reusable transform. <code> runs as a function body over the declared in params and
returns the out value:
A reusable message definition, referenced from a workflow instead of being written inline every time:
Routes describe how components are presented as a navigable app; they don't replace the components themselves.
A full example
xuda-studant-app-example is a complete source tree covering all eleven blocks: a login flow, a
routed dashboard, student roster, tasks and profile screens, table-backed reads and writes, and
Tailwind styling. Unpack it with:
Everything above is the interpreted dialect xuda-cli compiles: blocks parsed at save time into
progUi / progFields / progEvents runtime documents, read by the platform's expression-driven
renderer. A separate, unpublished compiler (@xuda/compiler, used by vite-plugin-xu) reads a
narrower .xu file made of only <template>, <script> and <style>, ignores the block names
above, and emits a real ES module ahead of time instead of a JSON document. It targets the newer
signals-based renderer in @xuda/core, the same engine the platform ships as
runtime/js/xuda_core.globals.js. See vite-plugin-xu and
@xuda/core for that path.