Build an app

Create a working application on Xeplr OS with @xeplr/cli, including sign-in, a guarded API, a React UI and a sample built with the screen designer.

npx @xeplr/cli@latest new myapp

@latest makes npx fetch the newest version instead of one it cached earlier. The command asks a few questions, writes the project, installs it and sets up its databases. The CLI has two commands, xeplr new and xeplr encrypt. See The CLI.

Before you start

brew services start redis            # macOS
sudo systemctl start redis           # Linux
docker run -d -p 6379:6379 redis     # Windows: Redis has no native build, so use Docker or WSL

Without Redis, login appears to work and then every request is refused as “Invalid or expired token”. The sign-in service checks for Redis at startup and refuses to start rather than let you run into that message.

It works on macOS, Linux and Windows, and nothing it generates depends on a Unix shell.

Questions it asks

Encryption keys and signing secrets are generated, never asked for.

Use a new project name for a new app. The name sets the database names (<name>_auth, <name>_api). An existing database is kept as it is, with its accounts, so the super admin you enter is created only in a fresh one.

If you skip the connection question

The setting is left blank, with npx @xeplr/cli encrypt written directly above it in api/development.env. Host, port, user and password are encrypted together into one string. A guessed value would start cleanly and read as empty data, so until you fill it in the app refuses to start and names the setting.

What you get

myapp/
├─ api/        the API and the sign-in service
├─ ui/         the React app
└─ CLAUDE.md   how to change this app, written for Claude and readable by people

• Sign-in. Login, register, forgot and reset password, activation, profile, change password, and the admin screens for users, roles and permissions (@xeplr/auth, @xeplr/ui-account).
• A guarded API. Every address needs a valid token. An address you want open has to be named explicitly.
• Tasks, a sample built with the screen designer. It is a list whose New and Edit open the task form in a popup and save as you type into an ordinary tasks table. Neither screen is written by hand. Both are screens, published when the API first starts.
• Configure UI for Super Admin, in the settings menu at the top right:
  • Forms: every form in the app. Create a new form (a label people see and a key that names its table), design its form and list, publish (which creates or changes its table), open it, and add it to the side rail.
  • Menu: rename, reorder and hide the side rail’s items.
• Multi-tenancy, if you asked for it. Every row is stamped with the company (or workspace) it was made in, every read sees only its own rows, membership is checked on every request, and choosing one is the first screen after sign-in.
• A welcome screen that checks it can reach everything and tells you which files to change first.
• READMEs at the root and in api/ and ui/, and a CLAUDE.md.

api/

ui/

Start it

The installer has already run npm install in both halves. If you gave the database connection, it also ran npm run setup, which creates both databases, the sign-in tables and the permissions.

cd myapp/api && npm run start-auth   # sign-in
cd myapp/api && npm run start-api    # your API; publishes the sample screens on first start
cd myapp/ui  && npm run dev          # the app

Open the UI and sign in with the account you named. As Super Admin, you see Configure UI in the settings menu.

xeplr new myapp --no-install only writes the files. After that, run npm install in api and ui, and npm run setup in api. If setup stops partway (Postgres not running, say), the installer names the step and the command to run again.

Commands in a generated project

Settings to know

Changing the database connection later

When a password rotates, the database moves, or the first answer was wrong, run this from the project’s api folder:

npm run db:encrypt

It reads the encryption key from your settings, asks for the database details and rewrites every connection setting. Outside a project (before npm install, or from any other folder), npx @xeplr/cli encrypt asks for the key too and prints the result instead of writing it.

Create a new UI

A new UI is a form: a list, plus an add/edit form that the list opens in a popup, saved in its own table. There are two ways to make one.

Without code

Go to Configure UI → Forms → New form → design → Publish → Add to menu.

A form made this way has no page, hooks or model files. Add them with the steps below when it needs them.

With Claude

Open Claude in the project folder and give it this prompt, which also appears beside the sample with a Copy button:

Create a new UI for farming departments. One record is a farming department with: Name (required), Region (dropdown: North, South, East, West), Area in acres (number, at least 0), Started on (date), Notes (long text). Show Name, Region and Area in the list. Follow “Create a new UI” in CLAUDE.md.

Change the name and the fields. You can add behaviour in the same message, such as “a Mark active button on each row”, “Region is required when Area is over 100” or “store tags as an array”.

Claude follows CLAUDE.md. <form> is singular (farming_department) and the page name is plural (FarmingDepartments).

1. The spec: api/screens/<form>/<form>.entity.json, copied from task.entity.json.
2. Screens and server files, from api/:

   npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages
   npx xeplr-factory validate screens/<form>/<form>-edit.screen.json
   npx xeplr-factory validate screens/<form>/<form>-list.screen.json

   This writes <form>-list.screen.json, <form>-edit.screen.json, <form>.hooks.js and <form>.model.js.
3. Registration in api/screens/index.js: both screens in documents (edit before list), the hooks under <form>_edit, the model in models.
4. The form’s page ui/src/pages/Edit<Form>.jsx, copied from EditTask.jsx, holding the front-end hooks. Every method calls super.
5. The list’s page ui/src/pages/<Forms>.jsx, copied from Tasks.jsx.
6. The route and side-rail item in ui/src/App.jsx. The drawerItems entry is by key and has an icon.
7. The menu row api/migrations-auth/000N_<forms>_menu.sql, whose name is the key spelled exactly as in drawerItems. Then run npm run migrate:auth and restart the sign-in service.
8. A restart of the API. It publishes the new screens, creates the table, and logs [api] published screens: <form>_edit, <form>_list.
9. A check: open the page, click New and fill in the form. The popup says “All changes saved” and the row is in the table.

After that, change only what the request asks for:

How screens, hooks and models work is covered in Forms and screens.

Rules the generated app follows

Last updated 16 September 2026