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