Build an App

These guides take you from an empty directory to a working revenexx App that serves a real API capability through the gateway. You build the app, run it against an in-memory data store on your laptop, deploy it with the revenexx CLI, and confirm it answers a real request at https://api.revenexx.com.

An App is the unit of installable business logic on Revenue Cloud. It owns its own data tables, exposes HTTP capabilities through the API gateway, and gets multi-tenancy, deployment, and API generation handled for you. You declare what the app is in a few JSON files and write the custom logic as a small Node function. For the bigger picture of what an App is and how it's published, read the App Marketplace overview.

What you'll build

A small Locations app: one entity (a stock location), full CRUD over the gateway, a custom batch endpoint, and a seeded default. By the end you'll have deployed it and called it live. The later guides add a second entity, relationships, a custom action route, and the deploy-and-verify loop in full.

Prerequisites

• The basics from Prerequisites — a revenexx account and a tenant slug.
• Node.js 22 or newer.
• The revenexx CLI installed and signed in (revenexx login).
• A machine-to-machine API key for your tenant, created in Cockpit. You send it as X-Revenexx-Api-Key when you call the gateway.

You write apps against the App SDK (@revenexx/app-sdk), which gives you a typed data client over your app's tables and a small HTTP router for the function.

The path

First command

revenexx create app locations --entity locations

revenexx create app <name> scaffolds the whole app in one command — see Scaffolding. Step 2 builds the same thing by hand so each file makes sense.

1. Your first App in 15 minutes — scaffold, deploy, and call it live.
2. Build your first App — scaffold the files, declare one entity, mount CRUD, generate the capability list, test locally, then deploy and verify with a single command each.
3. Add a data model — a second entity, a relationship, a custom action route with guards, and the typed data client in depth.
4. Deploy and verify an App — the full deploy-and-verify loop with the revenexx CLI, owner of the flags and the smoke test, plus a section of its own on caching read-heavy capabilities at the gateway.
5. Publish on the Marketplace — the manifest and billing fields a listing needs, the consent screen you are writing, and what changes once other tenants depend on you.
6. Ship a schema change — add a column to an App that tenants already have installed: what is safe, how to deploy and backfill, and what rolling back really means.
7. Ship a breaking change to an App — change a response callers already depend on: decide whether it is a break, ship the new capability beside the old one, deprecate the old one, and see what you cannot find out.
8. Publish a business event from your App — announce a fact that is not a row change: declare it, publish it after the write with an id that makes a retry harmless, test it with the mock adapter, and look up the topic consumers subscribe to.
9. React to events and run scheduled work in your App — answer the install event and run a nightly job once per tenant, make both safe to run twice, test them with the mock adapter, and see which reactions you can rely on today.
10. Give your App a Cockpit screen — add a sidebar entry, a list, a detail view, a create and edit form and a button that calls your own route, preview it on your machine, deploy it, and learn what a view's permissions key does and does not do.

Where to go next

• Operating an App — the routine after install day, what healthy looks like and what to hand over when you escalate. For a failing call, Debug a failed request.
• App SDK — the data client and router you build the app with.
• CLI — the command-line tool you deploy with.
• App Marketplace — what an App is and how publishing works.