Add a sidebar-navigated page
Goal: add a "Reports" link to the host EMR's sidebar that opens a new page you control.
Prerequisites:
- An Orion app generated with
orion initandnpm installd - Sandbox configured (
orion config sandbox) andorion devready to run
The mental model
A "navigated page" is two manifest entries in orion-app.json that point at the same path:
- a page extension (
extensions.pages[]) owns the route and renders the content - a nav extension (
extensions.navigation[]) puts a link to that route into the sidebar, header, settings, or patient-actions menu
You can have a page without a nav (deep-linked from a block or an action) or a nav without a page (linking to a host route), but the common case is both, generated together.
Step 1 — Pick the placement
The nav generator's --placement flag takes one of the four areas the host EMR exposes. Print them so you don't have to guess:
orion generate list navFor this recipe, sidebar. (Use the same list command for block, widget, and action catalog tokens.)
Step 2 — Generate the page first
Generate the page that owns /reports:
orion generate page reports --path /reportsThis writes:
- An entry under
extensions.pages[]inorion-app.jsonwithpath: "/reports"andcomponent: "Reports" src/pages/Reports.tsx— a placeholder page component you'll edit- An import of
Reportsinto your app's entry file (src/main.tsxorsrc/index.tsx)
On the legacy template the generator also writes the createPage(ReportsComponent) registration, so the page is fully wired after the next build. On the SMART template it prints the JSX snippet to paste into mount().
Step 3 — Generate the nav entry
Now add the sidebar link. Use a different <id> than the page — see the callout below for why:
orion generate nav reports-link --placement sidebar --path /reports --icon FileTextThis writes:
- An entry under
extensions.navigation[]inorion-app.jsonwithplacement: "sidebar"andtarget: "/reports" src/nav/ReportsLink.tsx— a placeholder file (nav entries don't render their own component; the host reads the link from the manifest)- An import of
ReportsLinkinto your entry file
--icon accepts any Lucide icon name. orion generate list nav reminds you of the placements; for icons, see lucide.dev.
Use a different <id> for the nav than for the page
Using reports for both would scaffold two named imports of Reports — one from @/pages/Reports, one from @/nav/Reports — into the same entry file. That's a duplicate identifier; tsc errors and the build fails. Keep the nav slug distinct (reports-link, reports-nav, etc.) and the imports stay clean.
Step 4 — Verify
orion devIn the host EMR sandbox, the sidebar gains a "Reports" entry. Click it — your placeholder src/pages/Reports.tsx renders inside the host frame. Edit the page; HMR picks up the change.
Recap
| Step | Command | What it lands |
|---|---|---|
| 1 | orion generate list nav | (read-only) prints valid placements |
| 2 | orion generate page reports --path /reports | page extension + src/pages/Reports.tsx + import |
| 3 | orion generate nav reports-link --placement sidebar --path /reports --icon FileText | nav extension + src/nav/ReportsLink.tsx + import |
| 4 | orion dev | renders in the sandbox |
Page-first matches the mental flow ("I built a thing, now I want people to find it"), but the order doesn't strictly matter — either way each generator writes its own manifest entry and source file, and the host resolves the sidebar link to the page at render time.
Related
- Manifest schema — the full field shape of page and navigation entries
- Development commands — the full
generatesurface, includinglist - Add a page that fetches FHIR data — what to put inside a generated page