Build your first UI

Run a small UI written in Acore, or add a generated client to the frontend you already have. Both consume a backend contract; they differ in setup and lifecycle.

Diagram source

flowchart LR
  A[Backend .axiom contract] --> B[Acore UI app]
  A --> C[Generated client in your existing app]

Option A: run an Acore UI

Acore UI is Alpha on the web, and on qualified Android Emulator and iOS Simulator paths.

Prerequisites

• Axiom CLI 0.149.1 and the web UI host 0.6.12 (axiom ui host install --target web --version 0.6.12 --non-interactive).
• A browser. Port 5173 free.

1. Create the starter

axiom ui init hello --target web
cd hello

Created authored Acore UI starter at hello. Next: axiom run src/main.acore --target web

The directory must be empty or new. It now holds axiom.app.toml, src/main.acore (a page with a greeting and a Reset button), tests/smoke.acore and a README.md. Pass --target web: axiom ui init defaults to ios.

2. Check and run it

axiom ui check src/main.acore --target web
axiom run src/main.acore --target web --port 5173

Checked UI module starter.app.ui (17 virtual read-only file(s), graph <hash>).
UI compiled (#1).
Axiom UI is ready at http://127.0.0.1:5173/ (pass --launch to open a browser)

3. Verify and edit

Open http://127.0.0.1:5173. The page shows Welcome to Axiom and a Reset button. Change the greeting text in src/main.acore and save; the running app reloads. This starter has no backend dependency. Stop it with Ctrl-C, and delete the hello directory when you are done.

Connect a backend

For a full-stack UI, keep a type = "frontend" manifest in the frontend's own directory and declare each backend under [contracts.<alias>]. The backend keeps its own type = "backend" manifest. This is the task app's frontend manifest:

type = "frontend"
targets = ["web"]

[contracts.tasks]
artifact = "../backend/.axiom/contracts/backend.axiom"
baseUrl = "http://127.0.0.1:8080"
audience = "web"
operations = ["create_task", "delete_task", "list_tasks", "update_task"]

axiom run finds the manifests, rebuilds stale local Acore dependencies and maintains the development lock. Explicit lock paths are an advanced override. Registered sandbox modules need their compatible toolchain and verification. See Imports, amends and variants for use contract.

android and ios targets need a compatible signed UI host and an emulator or simulator. Check each target separately before you claim parity; generated adapter tests do not prove a mounted native app.

Option B: use your existing frontend

Keep your application and generate a client for its framework:

For web and React, axiom pull runs the project's own atmx generator when it is installed. Otherwise it fetches atmx-cli at the CLI's version, and there is no atmx-cli 0.149.1 on npm. Install the published generator first. With a local contract built from your backend:

npm install --save-dev atmx-cli@0.146.7
axiom doctor
axiom onboard --role frontend --framework atmx-web
axiom pull --contract ../backend/backend.axiom --framework atmx-web

axiom pull writes the dependency declaration and generates the client. Keep the declaration and its lock together. Use atmx-react, flutter or dart only on the matching supported path, and qualify React separately. The FastAPI guide is a complete, tested web example. The SDK guides cover initialization, authentication, errors, caching and disposal.

Troubleshooting

Add data, forms and tests

Run your first app shows queries, contract-backed form validation, mutations, typed errors and list refresh. For browser-only experiments, the playground's database task and inventory examples let you edit source and inspect tables; Browser preview explains their simulated storage.

Next steps

• Run your first app
• Acore UI reference
• App lifecycle and targets
• Frontend tests