ORBPAGE DOCUMENTATION
OrbPage
OrbPage holds what editors write about your products, built from the sections your shop declares. What it does, what it leaves to you and where to start.
OrbPage is the content layer of a shop: pages, category content, templates, menus and forms. Your shop declares the sections editors build from, editors arrange them in the admin's Content area, and the shop reads what they publish. Products, categories and pictures come from OrbCatalog and are never copied.
The shop reads a category's page through @orbpage/client, typed by the sections it declared. env.PAGE_URL is where OrbPage answers:
import { createClient } from "@orbpage/client";
import { sections } from "./sections";
const content = createClient({
baseUrl: env.PAGE_URL, // where OrbPage answers, such as https://content.nordgrat.de
sections,
});const read = await content.categories.get("outdoor/rucksaecke", { locale: "de" });
if (read.ok) {
read.content.slots.top; // the hero sections, typed by the declaration
read.content.slots.main;
read.content.template; // the template it follows
read.content.meta.unresolved; // what was left out, such as a product no longer sold
} else {
read.problem.code; // such as "entry_not_found", "unreachable" or "unexpected_response"
}No read throws. When OrbPage cannot answer, the shop still shows the catalog's category, without the editor's slots. Read the content covers pages, menus and previews.
What OrbPage does
- Builds pages from your sections. The shop declares sections with typed settings and the slots they go in. The editor, drafts, publishing and delivery all check against that one declaration.
- Shares a template across categories. A category follows its template slot by slot until an editor makes a slot its own. A reset gives the slot back to the template.
- Shows the draft in your shop. The admin previews an editor's draft inside the shop's own page, in a frame. The preview reads the draft uncached, under a short-lived token.
- Delivers JSON and Markdown. Running text arrives as safe HTML inside JSON. A card whose product went away is left out and named in
meta.unresolved. - Takes form answers. Answers land in a separate Inbox for 180 days. Each accepted answer can send a signed
form.submittedevent. - Tells your systems what went live. Configured, every publish, rollback or withdrawal sends a signed
content.publishedevent. - Lets AI agents propose drafts. An agent proposes a page or template change over MCP, rows of columns included, a person approves it in the admin, and publishing stays a separate step.
What OrbPage leaves to you
| OrbPage does not | Who does |
|---|---|
| Render or style the shop | Your storefront. @orbpage/react adds the row layout and the preview marks. |
| Keep products or pictures | OrbCatalog, read at delivery, with its media library. |
| Show prices or stock on cards | Your shop. A card holds a name, an address and a picture. |
| Send emails | A receiver of the signed form.submitted event. |
| Run on someone else's servers | You do: one Worker in your own Cloudflare account. See deployment. |
Change what you need
Everything in OrbPage changes in one of three ways, from shallow to deep.
| Depth | You | Example |
|---|---|---|
| Configure | Set values in the shop's declaration. | A setting's default and help text, the palette, the menus. |
| Compose | Let editors arrange the declared sections. | Rows in six layouts, templates. |
| Replace | Render each section with your own component. | A switch over the section's type. |
Built on OrbCatalog
OrbPage needs OrbCatalog and does not run without it. It reads products, categories and listings through @orbcatalog/client at delivery, and its site's languages are the ones its catalog Channel sells. OrbPage needs neither OrbCart nor OrbSearch. Connect the products shows the configuration.
Next steps
| You want to | Read |
|---|---|
| See it run | Run it locally |
| Declare the shop's sections | Declare sections and slots |
| Read pages, menus and previews | Read the content |
| Seed or import pages from a script | Write content from code |
| Point OrbPage at the catalog | Connect the products |
| Set it up in your Cloudflare account | Deployment |