Building on Stage

These pages are for the person building or extending a Stage site. They describe the contract: what a site renders so the admin can edit it, what it declares so the admin can add to it, and what it emits so Stage can measure it. How the editor behaves for a user is in the Guides; these pages link there rather than repeat it.

What a Stage site is

                          Stage database
                (PostgreSQL + auth + realtime)
                              |
          +-------------------+-------------------+
          |                                       |
     Your site                              Stage API
  (static build, one                    (one shared service)
   deployment per site)                 uploads, publishing,
          |                             posting, links, forms,
   +------+------+                      analytics reads
   |             |                                |
 public       /admin  ───────────────────────────▶│
 pages     (same-origin frame
 (no editor  + the admin shell)
  JS)

Part	What it is	Who runs it
The site	An Astro static build. Pages, articles, globals and media are read from the database at build time and rendered to HTML with inert edit anchors. No editor code ships to visitors. The SDK’s small inline scripts for consent and engagement do, and form submission needs JavaScript	Deployed once per site, on the site’s own domain
The admin	`/admin` on the same domain. A top bar hosting lazily loaded tools. Generic: it edits any component by id and path and contains no design	Loaded only for a signed-in member
The API	One service, deployed once, shared by every site. Holds every secret. Every route is org-scoped	Operated by Stage
The database	Every content, media and analytics row carries an `org_id`. Row-level security enforces the scope	Operated by Stage

The two packages

Package	Contains
`@sp-stage/sdk`	Pure data and logic. Queries, the id and path write model, versioned saves and merge, the anchor helpers, the edge middleware, image URL helpers, sanitisers, the analytics scripts
`@sp-stage/admin`	The `/admin` shell and its tools (React)
`@sp-stage/next`	Next.js sites only: the anchors as React props, the admin mount, the zero-JS edit canvas, the publish handler. See Next.js sites

A site pins an exact version of both. They release together as one Stage version. See Versioning and releases.

The contract in one paragraph

A site renders each stored component through its own renderer and spreads the anchor helpers onto the wrapper and every editable field. That alone makes existing content editable. To make lists addable, the site passes a schema to the admin naming which fields are lists and what a new item looks like. To be measured, the site re-exports the SDK middleware and includes the SDK’s inline scripts in its layout. Nothing in the platform knows a site’s design.

Read in order

Set up a site

The template, the env, the admin mount, local development. Read it.

Make content editable

Anchors, components, and the write model underneath.

Make content addable

Schemas, the edit notch, then the blog and forms recipes.

Measure

Tracking, campaign landing, and custom funnels.

Stage only. These pages document the platform contract. How a particular site’s design is produced (design tools, generators, internal playbooks) is not Stage and is not here.

Start

Making content editable

Making content addable

Media

Next.js

Analytics SDK

Platform reference

Building on Stage

What a Stage site is

The two packages

The contract in one paragraph

Read in order

​What a Stage site is

​The two packages

​The contract in one paragraph

​Read in order

What a Stage site is

The two packages

The contract in one paragraph

Read in order