Skip to content
Verified

Install and create a project

Scaffold a Xuda CLI project with one command, then learn what every generated file is for.

Before you start

The CLI path needs Node.js 18.17.0 or newer, which is the engine floor xuda-cli declares. Nothing else: xuda-cli itself depends on three packages (express, socket.io, chokidar), and the scaffolder that creates a new project has no dependencies of its own. Local development never calls a plan-gated method, so building an app this way costs nothing.

Scaffold a new app

bash
npm create xuda-cli@latest my-app
cd my-app
npm install
npm run dev

See what create-xuda-cli wrote

The scaffolder writes a package.json already declaring @xuda.io/xuda-framework-plugin-tailwind and @xuda.io/xuda-dbs-plugin-xuda as dependencies and xuda-cli as a dev dependency, a xuda.config.js, App.xu, index.html, a components/ folder, and a first node_modules/.project_data/globals.json. It also drops a generated README.md guide into twelve folders: the eleven typed source folders plus one for data/ itself, each one removable later.

Open the app

npm run dev prints the URL it listens on, http://localhost:3000 by default. index.html is served as the shell and App.xu mounts into #app automatically, because the scaffolded config sets entry: 'index.html' and no other component claims that element. App.xu always compiles to the program id app.

Edit and save

Edit App.xu and save. The watcher recompiles the project, regenerates the runtime documents, and pushes a reload over a socket.io channel, so the browser refreshes itself.

Clear the folder guides once you don't need them

bash
npm run clean:readmes

This only deletes the README files the scaffolder generated (tracked by an internal marker). Any README you wrote yourself is left alone, and the command reports removed, skipped and missing counts separately.

The mental model: three layers

If xuda.config.js sets entry: 'index.html', the HTML shell is served first and App.xu mounts into #app unless something else already claimed that element. If entry is omitted, xuda-cli defaults to the program id app instead of an HTML file.

Recommended split: keep index.html as the page shell, keep App.xu as the root screen, and add feature screens under components/.

The project layout

my-app/  package.json  xuda.config.js  index.html  App.xu
components/ globals/ data/ get/ set/ batch/ apis/ scripts/ alerts/ tables/ routes/ ai-agents/
node_modules/ .project_data/

See The .xu language for what belongs in each folder and how the folder a file sits in decides its unit type.

xuda.config.js

js
module.exports = {
  entry: 'index.html',
  port: 3000,
  ssr: 'none',
  api_key: '',
  build_id: '',
};
Leave build_id unset

Setting build_id also makes api_key mandatory, and it targets a remote build path that has no implementation behind it yet, so the project will fail to load rather than build remotely.

Everything else about commands, SSR modes and cloud sync lives on The CLI reference.

Generated runtime docs

xuda-cli always compiles runtime docs into node_modules/.project_data/, one globals.json plus one file per program. Stale files there are deleted on every compile. Treat it as build output: the .xu and .json5 files you write are the source of truth.

You may see a project_data/ folder or a root .project_data/ folder in older material. Those are legacy import-only paths kept for migration, never a place to write.