# xuda-cli
`xuda-cli` is the local development CLI for Xuda app projects.
It lets you:
- create and run a Xuda app locally
- author the app in friendly source files such as `App.xu`, `components/*.xu`, and `tables/*.json5`
- compile those source files into runtime JSON docs
- keep the runtime docs in one canonical location: `node_modules/.project_data/`
- optionally sync cloud project docs down into source files and push local changes back up
## Quick Start
Create a new app:
```bash
npm create xuda-cli@latest my-app
cd my-app
npm install
npm run dev
```
Typical `package.json` scripts:
```json
{
"scripts": {
"dev": "xuda-cli dev",
"sync": "xuda-cli sync"
}
}
```
Install common plugins with normal npm install:
```bash
npm install @xuda.io/xuda-framework-plugin-tailwind
npm install @xuda.io/xuda-dbs-plugin-xuda
```
There is no plugin subcommand in `xuda-cli`.
## Commands
```bash
xuda-cli dev
xuda-cli sync
xuda-cli --help
```
`xuda-cli dev`
- loads your project from the current directory
- compiles source files into `node_modules/.project_data/`
- serves the app locally
- watches `.xu` and supported `.json5` files and regenerates runtime docs on save
`xuda-cli sync`
- requires `api_key` in `xuda.config.js`
- downloads cloud docs into `node_modules/.project_data/`
- creates missing local `.xu` and `.json5` source files from those docs
- recompiles local source back into `node_modules/.project_data/`
- uploads changed docs back to the cloud
## Mental Model
The app has three important layers:
1. `index.html`
This is the document shell. It owns the ``, metadata, fonts, and the HTML node where your root app mounts.
2. `App.xu`
This is the root Xuda screen. It is compiled as the program id `app`.
3. `node_modules/.project_data/`
This is the generated runtime document set that the Xuda runtime reads.
If `xuda.config.js` uses:
```js
module.exports = {
entry: 'index.html'
};
```
then `index.html` is served first, and `App.xu` is automatically mounted into `#app` unless you already mounted another component into that HTML entry.
If `entry` is omitted, `xuda-cli` defaults to `app`.
Recommended rule:
- keep `index.html` as the page shell
- keep `App.xu` as the root Xuda screen
- add feature screens under `components/`
## How `xuda-cli` Technology Works
`xuda-cli` is not just a file server. It is a source compiler, runtime packager, local app host, and optional cloud sync tool.
When you work on a Xuda app, the technology flow looks like this:
1. Authoring layer
You write human-friendly source files such as `App.xu`, `components/*.xu`, `data/get/*.xu`, and `tables/*.table.json5`.
2. Compile layer
`xuda-cli` parses those source files and converts them into the JSON document model that the Xuda runtime already understands.
3. Runtime docs layer
The compiled output is written to `node_modules/.project_data/`. This is the canonical runtime doc folder used by the local app.
4. Runtime host layer
`xuda-cli dev` serves your `index.html`, runtime assets, compiled component scripts, and the generated document set.
5. Browser/runtime execution layer
The browser loads the Xuda runtime, mounts `App.xu` or the configured entry program, and executes fields, actions, events, datasources, and panels.
6. Optional cloud sync layer
If `api_key` is configured, `xuda-cli sync` can pull remote docs into the local project, create missing source files, and push changed docs back to the cloud.
### Source-first philosophy
The intended developer experience is:
- source files are the place humans edit
- `node_modules/.project_data/` is generated runtime output
- the runtime reads generated docs
- sync can import older or remote docs into source files, but source remains the preferred authoring format
### What gets compiled
`xuda-cli` compiles:
- `.xu` files into component or logic-unit docs
- `.table.json5` files into table docs
- `.route.json5` files into route docs
- `.agent.json5` files into AI agent docs
### What stays runtime-facing
The local runtime still consumes the classic Xuda document shape:
- `progUi`
- `progFields`
- `progEvents`
- `progDataSource`
- `tableFields`
- `tableIndexes`
- `routeMenu`
- `agentConfig`
That means `xuda-cli` gives you a friendlier source format without requiring a brand-new runtime protocol.
### SSR and render profiles
`xuda-cli` supports:
- `ssr: 'none'`
- `ssr: 'first_page'`
- `ssr: 'full'`
In practice:
- `none`
normal client rendering
- `first_page`
first-page SSR with client takeover
- `full`
fuller SSR with hydration-friendly behavior
### Plugin model
Plugins are standard npm dependencies, not copied folders and not special CLI subcommands.
Use plugins for:
- UI frameworks such as `@xuda.io/xuda-framework-plugin-tailwind`
- database behavior such as `@xuda.io/xuda-dbs-plugin-xuda`
### Why the project keeps both `index.html` and `App.xu`
They solve different problems:
- `index.html`
document shell, metadata, fonts, mount element
- `App.xu`
root Xuda UI, fields, actions, panels, and app behavior
This separation keeps the app structure predictable and makes it easier to scale into multiple routed or panel-based screens.
## Project Layout
This is the official source layout:
```text
my-app/
package.json
xuda.config.js
index.html
App.xu
components/
**/*.xu
globals/
**/*.xu
data/
get/**/*.xu
set/**/*.xu
batch/**/*.xu
apis/
**/*.xu
scripts/
**/*.xu
alerts/
**/*.xu
tables/
**/*.table.json5
routes/
**/*.route.json5
ai-agents/
**/*.agent.json5
node_modules/
.project_data/
```
Rules:
- `App.xu` is the reserved root app file
- `components/` is for UI components
- `globals/` is for shared state units
- `data/get/`, `data/set/`, and `data/batch/` are for logic units
- `tables/`, `routes/`, and `ai-agents/` are structured JSON5 resources
- `node_modules/.project_data/` is generated runtime output, not your source of truth
## What Lives in `index.html`
Use `index.html` for:
- the page title
- meta tags
- favicons
- fonts
- external scripts if you need them
- the root mount element
Minimal example:
```html
My Xuda App
```
## `xuda.config.js`
`xuda.config.js` controls entry, server, and sync-related settings.
Example:
```js
module.exports = {
entry: 'index.html',
port: 3000,
ssr: 'none',
api_key: '',
build_id: ''
};
```
Supported fields:
- `entry`
The app entry. Usually `index.html`. Defaults to `app`.
- `port`
Local dev port. Defaults to `3000`.
- `ssr`
One of `none`, `first_page`, or `full`.
- `api_key`
Optional. Required for `npm run sync`.
- `build_id`
Optional remote build target. If provided, it requires `api_key`.
## `package.json`
`package.json` is the source of app package metadata:
- `name`
- `version`
- `description`
Minimal example:
```json
{
"name": "my-app",
"version": "0.1.0",
"description": "Starter Xuda app",
"scripts": {
"dev": "xuda-cli dev",
"sync": "xuda-cli sync"
},
"dependencies": {
"@xuda.io/xuda-framework-plugin-tailwind": "latest",
"@xuda.io/xuda-dbs-plugin-xuda": "latest"
},
"devDependencies": {
"xuda-cli": "latest"
}
}
```
## Source File Types
`xuda-cli` supports these authored source types:
| Location | File type | Xuda unit |
| --- | --- | --- |
| `App.xu` | `.xu` | root `component` |
| `components/**/*.xu` | `.xu` | `component` |
| `globals/**/*.xu` | `.xu` | `globals` |
| `data/get/**/*.xu` | `.xu` | `get_data` |
| `data/set/**/*.xu` | `.xu` | `set_data` |
| `data/batch/**/*.xu` | `.xu` | `batch` |
| `apis/**/*.xu` | `.xu` | `api` |
| `scripts/**/*.xu` | `.xu` | `javascript` |
| `alerts/**/*.xu` | `.xu` | `alert` |
| `tables/**/*.table.json5` | `.json5` | `table` |
| `routes/**/*.route.json5` | `.json5` | `route` |
| `ai-agents/**/*.agent.json5` | `.json5` | `ai_agent` |
## Xuda Building Blocks At A Glance
Each block exists for a different responsibility. A good Xuda app is usually clearer when each concern has its own unit instead of pushing everything into one giant component.
| Building block | Main responsibility | Best used for |
| --- | --- | --- |
| `component` | UI and interaction | screens, panels, forms, dashboards, reusable views |
| `globals` | shared app state | signed-in user, campus, feature flags, shared filters |
| `get_data` | reading data | list loads, record queries, reusable data fetches |
| `set_data` | writing data | create, update, delete, persistence workflows |
| `batch` | record-by-record processing | rebuild jobs, migration flows, recalculation |
| `api` | response-oriented logic | API outputs, summaries, machine-readable endpoints |
| `javascript` | custom JS logic | formatting, transformations, reusable computation |
| `alert` | user messaging | toasts, success notices, warnings, error feedback |
| `table` | data model definition | fields, indexes, database-facing schema metadata |
| `route` | navigation model | menus, destinations, route planning |
| `ai_agent` | assistant configuration | app-specific AI helpers and future agent workflows |
### How to choose the right block
Use `component` when:
- the user sees it
- it owns UI state or user interactions
- it renders template markup
Use `globals` when:
- more than one screen needs the same state
- the value is app-wide rather than screen-local
Use `get_data` when:
- the main job is to read from a datasource
- you want loading logic to stay outside UI components
Use `set_data` when:
- the main job is to persist a change
- you want writes to have a named, reusable unit
Use `batch` when:
- you are processing many rows or records
- the workflow is iterative and not just a simple read/write
Use `api` when:
- the result should be shaped as a clean response
- the unit feels more like an endpoint than a screen
Use `javascript` when:
- you need custom code but do not want it scattered through actions
- the logic is reusable and named
Use `alert` when:
- the app needs consistent messaging
- a message should be reusable across multiple screens or workflows
Use `table` when:
- a datasource refers to real table-backed storage
- you need fields and indexes with a stable id
Use `route` when:
- the app has named destinations or menu structure
- you want a navigation model that is visible in source
Use `ai_agent` when:
- the app needs a configured assistant resource
- you want that assistant defined as a first-class app asset
## `.xu` Blocks
`xuda-cli` reads `.xu` files as block-based source files.
Supported component blocks:
- ``
- ``
- ``
- ``
- ``
- ``
- ``
- `
```
If the default export returns a function, that function is used as a disposer on unload.
Component `