Recipes
A recipe describes one behaviour that Cardinal's own apps implement, as the rules an app must follow and a short reference implementation in TypeScript. Recipes cover logic only: how the app looks, and which framework it is built with, are up to the app.
Each reference implementation uses only fetch and standard web APIs, so it ports to React, Swift, Kotlin, or any other platform. Each one is the logic, not an app.
| Recipe | What it covers |
|---|---|
| Connecting and staying connected | Reopening the last address, probing Remote Access candidates, and moving to a new address when the old one stops answering |
| Playback and the queue | Server-side queues, stream URLs, reporting plays to history, and resuming after a connection change |
| Live updates with events | Keeping the event stream open, and which data to refresh for each event |
| Permissions in the UI | Reading the user's roles, showing only what they can use, and handling refusals |
The credential and the base URL
Every recipe reaches the server through the same two functions. Keeping them the only code that knows how the app signs in and where the server is lets the app change its sign-in method, or follow the server to a new address, without touching anything else.
// A current credential for the Media Server. With `refresh`, renew it first if the
// sign-in method supports renewal; a personal access token is returned unchanged.
declare function getToken(options?: { refresh?: boolean }): Promise<string>
// The server's base URL right now, such as "http://192.168.1.40:24900".
// Read it for every request; it can change while the app runs.
declare function getOrigin(): string | null
Implement getToken() with a personal access token or password login. A way for apps to request access to other people's accounts is planned; when it arrives, only getToken() changes. The Connecting recipe implements getOrigin(), and an api() helper that the other recipes use.
Using a recipe with a coding agent
The build-a-cardinal-app skill sends an agent to each recipe at the step where it applies. To use one on its own, give the agent the recipe's Markdown URL, for example:
https://help.cardinalapps.io/guides/diy-apps/recipes/playback-and-the-queue.md
Was this article helpful?