Development
Commands you'll run dozens of times a day while building.
orion dev
Run your app locally and let the host EMR iframe it for live preview. The CLI starts a Vite dev server, opens a Cloudflare tunnel, and registers the tunnel with your sandbox tenant.
orion devThe CLI prints the local Vite URL, the resolved tunnel URL, and registers the tunnel with your sandbox tenant. Save a file in your editor to trigger HMR inside the iframe.
Flags
| Flag | Default | Purpose |
|---|---|---|
-p, --port <port> | 5173 | Dev server port. |
--no-tunnel | — | Skip the tunnel. Only useful if you've configured the sandbox to reach localhost directly (rare). |
The CLI bundles cloudflared via the npm cloudflared dev dependency and invokes that binary directly. There's a --tunnel-provider flag that's parsed for forward compatibility, but cloudflared is the only provider currently wired through.
Requires
orion config sandbox must be set. orion dev won't fall back to the home tenant — this is intentional, so dev code never runs against your home tenant. See Host vs Sandbox.
orion build
Run your production build into dist/.
orion buildFlags
| Flag | Default | Purpose |
|---|---|---|
-o, --out-dir <dir> | dist | Output directory. Override only if your vite.config.ts already does. |
--no-minify | — | Disable minification (useful when chasing a stack trace through the bundle). |
--sourcemap | — | Emit source maps. |
orion validate
Run all the checks orion publish runs, but stop before authentication and upload — manifest schema, bundle layout, scope rules, archive forbidden-paths. Catches issues early so you fix them before authentication and upload.
orion validateThe CLI prints one section per check group (Manifest (orion-app.json), Bundle (dist/index.js), Source archive) followed by a summary line — 0 problems found., 0 problems, 1 warning., or 2 problems, 0 warnings.
publish runs validate too — running it explicitly during development gives you faster feedback.
Schema checks include the extensions.writableExtensions block when present: required fields (key, title, valueType, appliesTo), kebab-case key shape, the 9-value-type allow-list, duplicate keys across entries, and the 50-entry manifest cap. Mismatches surface with the offending index and field name — fix in orion-app.json and rerun.
Flags
| Flag | Purpose |
|---|---|
--manifest | Validate the manifest only; skip bundle + source-archive checks. Useful for checking a manifest before npm run build. |
--json | Emit findings as newline-delimited JSON, one record per line. CI-friendly. |
orion doctor
Environment + manifest health check. Validates Node/npm versions, working-directory config, manifest shape, build artifacts, and (optionally) network reachability of the host tenant.
orion doctorSections checked: Environment, Authentication (local), Working directory, Manifest, Build, and (with --network) Identity. Each check is ✓ (pass), ! (warn), or ✗ (fail). A ✗ exits non-zero.
Flags
| Flag | Purpose |
|---|---|
--json | Machine-readable JSON output for CI scripting. |
--network | Opt-in remote-identity verification. Otherwise the doctor stays local-only. |
orion generate <kind> <id>
Aliased as orion g. Scaffold a new extension into the current app — manifest entry plus the corresponding source file. The available mount points, triggers, and placements match what the host EMR currently supports.
orion generate page reports --path /reports
orion generate block status-bar --target encounter-detail/status-bar --action after
orion generate widget patient-vitals --mount-point patient-detail-sidebar
orion generate action send-summary --trigger patient-context-menu
orion generate nav reports --placement sidebar --path /reports --icon FileTextKinds
| Kind | Required flags | Optional flags |
|---|---|---|
page <id> | — | --path <path> (default /<id>), --layout app|fullscreen|modal (default app) |
block <id> | --target <name> | --action before|after (default before) |
widget <id> | --mount-point <slot> | — |
action <id> | --trigger <name> | — |
nav <id> | --placement <name>, --path <path> | --icon <lucide-icon> (default LayoutDashboard) |
All subcommands accept --force to skip catalog/collision/overwrite checks.
For the field shape of each manifest entry generate writes (and how to hand-edit one), see Manifest schema.
Listing the catalog
To see which tokens are valid for --target, --mount-point, --trigger, and --placement without having to guess and read the rejection error, use:
orion generate list # all four catalogs, grouped
orion generate list block # just block targets
orion generate list widget # just widget mount points
orion generate list action # just action triggers
orion generate list nav # just nav placements
orion generate list --json # machine-readable outputThe values match what the host EMR currently supports. Drift here is a bug — file an issue if your dev server accepts a token list doesn't print, or vice versa.
What it writes
For each invocation, generate writes two things:
- An entry under the matching
extensions.pages[]/extensions.blocks[]/extensions.widgets[]/extensions.actions[]/extensions.navigation[]array inorion-app.json. - A starter source file in the matching plural directory (
src/pages/,src/blocks/,src/widgets/,src/actions/, orsrc/nav/) named<PascalCaseId>.tsx(.tsfor actions). The generator also adds an import for the new component to your entry file (src/main.tsxor equivalent) — wire the route or mount manually.
Kind reference
Five extension kinds, each with its own host surface and scaffolded shape. The table at the top of this section gives the quick syntax; the entries below cover what each kind is, where the host renders it, and what the generator drops on disk.
For the full manifest field shape of each kind, see Manifest schema.
Page (page) — full-page extension that owns a route
A full-page extension that owns a route inside the host EMR. The host renders your component edge-to-edge inside the app frame when the user navigates to the path you declared.
When to use it: anything that needs its own dedicated screen — dashboards, list views, settings panels.
orion generate page reports --path /reports writes:
extensions.pages[]entry:{ id, path, title, component, layout }(layoutisapp | fullscreen | modal, defaults toapp).src/pages/Reports.tsx— aReports()component returning a centered Card with a "Get started" placeholder and a Button. The component uses@orion-ehr/uiprimitives so it matches the host's design tokens out of the box.
Wiring: on the legacy template the generator also writes the createPage(ReportsComponent) registration into your entry file; on the SMART template it prints the JSX snippet to paste into mount().
Block (block) — small inline component injected into a host slot
A small inline component injected into one of the host's named slots — typically a row of metadata on a detail screen (encounter status bar, patient sidebar header, case overview stats). The host renders your component before or after the slot's own content; multiple blocks from different apps stack at the same slot.
When to use it: in-context additions that should sit next to existing host UI rather than take over a screen.
orion generate block status-bar --target encounter-detail/status-bar --action after writes:
extensions.blocks[]entry:{ id, target, action, component }(actionisbefore | after, defaults tobefore).src/blocks/StatusBar.tsx— a Card-wrapped component with the slot path captured in the file's doc-block so you can grep your way back to the manifest.
Discover valid --target values with orion generate list block — the host publishes a fixed catalog of slots; arbitrary strings are rejected.
Widget (widget) — persistent panel rendered in a fixed host region
A persistent panel rendered in a fixed host region: the patient detail sidebar, the dashboard widgets row, an appointment sidebar. Unlike a block (which annotates an existing row), a widget owns its container.
When to use it: panels that should be visible while the user is in a host context — quick reference data, action shortcuts, embedded charts.
orion generate widget patient-vitals --mount-point patient-detail-sidebar writes:
extensions.widgets[]entry:{ id, mountPoint, title, component }.src/widgets/PatientVitals.tsx— a Card with the widget's title and a body placeholder.
Discover valid --mount-point values with orion generate list widget. Two widgets at the same mount point stack vertically in declaration order.
Action (action) — headless handler invoked from a menu, palette, or toolbar
A headless handler invoked from a host menu, command palette pick, or toolbar press. Actions don't render UI themselves — they expose a default-exported async function the host calls when the trigger fires. The host owns presentation (the menu row label, the palette icon, the toolbar position); your code owns the behavior.
When to use it: behaviors attached to a host UI surface — "export this patient's record," "send to fax queue," "fire a workflow." Use a block or widget if you need to draw anything.
orion generate action send-summary --trigger patient-context-menu writes:
extensions.actions[]entry:{ id, trigger, title, handler }.src/actions/SendSummary.ts(note:.ts, not.tsx) — an asyncSendSummary(ctx)function with a typedContextinterface declaring the optional ids the trigger carries (e.g.patientId,appointmentId).
Discover valid --trigger values with orion generate list action.
Nav (nav) — link in the sidebar, header, settings, or patient-actions menu
A navigation entry — a link in the sidebar, header, settings menu, or patient-actions menu that routes to a path. The host owns the rendering; you provide the placement, target path, and icon.
When to use it: every time you want users to be able to reach a page you've built. Nav entries pair naturally with generate page (see the sidebar-navigated page recipe).
orion generate nav reports --placement sidebar --path /reports --icon FileText writes:
extensions.navigation[]entry:{ id, title, icon, placement, target }(the manifest field istarget; the CLI flag is--pathfor readability).src/nav/Reports.tsx— a stub component returningnull. Nav entries are almost always pure manifest data; the file exists so the manifest's optional component reference still resolves at build time.
Discover valid --placement values with orion generate list nav. --icon accepts any Lucide icon name (defaults to LayoutDashboard).