Skip to content
Verified

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="...">:

xml
<mount>
{
  id: "marketing_hero",
  file: "landing.html",
  selector: "#hero"
}
</mount>

The template language

Inside <template>, a small set of friendly aliases compiles down to the runtime's own xu-* markup.

xml
<template>
  <single-view>
    <section class="screen">
      <input bind="search_v" placeholder="Search students">
      <button @click="togglePanel">Toggle panel</button>

      <div if="@show_panel_v">
        <panel program="student_details" />
      </div>
    </section>
  </single-view>
</template>

A component, end to end

xml
<meta lang="json5">
{
  id: "student_list",
  menuTitle: "Student List",
  uiFramework: "@xuda.io/xuda-framework-plugin-tailwind"
}
</meta>

<fields lang="json5">
{
  show_panel_v: { type: "boolean", value: false },
  student_count_v: { type: "number", value: 3 }
}
</fields>

<actions lang="json5">
{
  togglePanel: [
    { action: "update", name: { value: "@show_panel_v: !@show_panel_v" } }
  ]
}
</actions>

<template>
  <single-view>
    <section class="p-6 space-y-4">
      <h1>Students</h1>
      <p :content="'Count: ' + @student_count_v"></p>
      <button class="rounded-full px-4 py-2 bg-sky-600 text-white" @click="togglePanel">
        Toggle details
      </button>
      <div if="@show_panel_v">
        <panel program="student_details" />
      </div>
    </section>
  </single-view>
</template>

<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.

xml
<datasource lang="json5">
{
  type: "table",
  table: "student_profiles_table",
  filter: {
    mode: "index",
    activeIndex: "campus_idx",
    indexes: {
      campus_idx: { campus: { from: "@campus_in", to: "@campus_in" } }
    }
  },
  output: "students_out",
  direction: "asc",
  realtime: true,
  limit: 25
}
</datasource>
xml
<datasource lang="json5">
{
  type: "table",
  table: "student_tasks_table",
  filter: {
    mode: "query",
    query: { $and: [{ status: "Open" }, { campus: "Boston Campus" }] }
  },
  output: "tasks_out"
}
</datasource>
xml
<datasource lang="json5">
{
  type: "json",
  source: { url: "https://example.com/students.json" },
  output: "students_out"
}
</datasource>
xml
<datasource lang="json5" mode="raw">
{
  "dataSourceType": "table",
  "dataSourceTableId": "student_profiles_table"
}
</datasource>

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:

xml
<response>
({ ok: true, count: (@students_out || []).length, rows: @students_out })
</response>

A named, reusable transform. <code> runs as a function body over the declared in params and returns the out value:

xml
<code>
return (@raw_name_in || "")
  .trim()
  .toLowerCase()
  .replace(/\b\w/g, (letter) => letter.toUpperCase());
</code>

A reusable message definition, referenced from a workflow instead of being written inline every time:

xml
<alert lang="json5">
{
  alertDisplay: "toast",
  alertType: "success",
  alertTitle: "Student saved",
  createLog: false
}
</alert>
json5
{
  id: "student_profiles_table",
  menuTitle: "Student Profiles Table",
  fields: [
    { field_id: "student_id", type: "string" },
    { field_id: "full_name", type: "string" }
  ],
  indexes: [{ id: "campus_idx", name: "Campus", keys: ["campus"] }]
}
json5
{
  id: "app_route",
  menuTitle: "App Route",
  menu: [
    { title: "Overview", prog: "app" },
    { title: "Students", prog: "student_list" }
  ]
}

Routes describe how components are presented as a navigable app; they don't replace the components themselves.

json5
{
  id: "class_helper",
  menuTitle: "Class Helper",
  config: { provider: "openai", model: "gpt-5" }
}

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:

bash
mkdir xuda-studant-app-example
cd xuda-studant-app-example
npm pack xuda-studant-app-example
tar -xzf xuda-studant-app-example-*.tgz --strip-components=1 package
rm xuda-studant-app-example-*.tgz
npm install
npm run dev
A second, build-time dialect exists too

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.