Set up a site

What you start from

This page is the Astro template, the default. A Next.js site uses the Next template and the @sp-stage/next adapter; see Next.js sites.

The client template is a minimal Astro site that already meets the whole contract: the SDK initialised, the middleware re-exported, the /admin mount, a reference Hero component, the blog and forms renderers, the header and footer globals, the consent banner, and the analytics scripts in the base layout. Clone it and build the design out from there.

src/
├── components/
│   ├── global/     Header, Footer, Media, FormOverlay, ConsentBanner
│   ├── home/       Hero (the reference component)
│   ├── blog/       ArticleList, ArticleBody, Prose
│   └── forms/      the six question renderers, PageBreak, FormBody
├── layouts/Base.astro     SEO, analytics scripts, header and footer
├── lib/
│   ├── stage.ts           SDK init
│   ├── components.ts      component type → renderer
│   ├── stage-anchors.ts   the anchor helpers, re-exported from the SDK
│   └── admin-schema.ts    what the admin can add
├── pages/
│   ├── index.astro, [...slug].astro     public pages
│   ├── news/                            articles
│   ├── preview/                         the gated edit canvas
│   └── admin.astro                      the /admin mount
middleware.ts                            re-exports the SDK middleware

A standalone site installs @sp-stage/sdk and @sp-stage/admin from the private registry at an exact version. In the platform monorepo the template consumes them from source.

Environment

Variable	What it is
`STAGE_DB_URL`, `STAGE_PUBLIC_KEY`	The database URL and its public key. Shared across sites. Read through `lib/platform-env.ts`, which fails at first import if either is missing
`ORG_ID`	This site’s org. Every read and write is scoped by it
`SITE_URL`	The canonical domain, `www` included if that is where the site lives. Campaign links are minted against the org’s site URL
`API_URL`	The shared API base, no trailing slash. Enables uploads, settings, publishing and requests from `/admin`
`ADMIN_LOGO_URL`, `ADMIN_BRAND_NAME`, `ADMIN_LOGO_FONT`, `ADMIN_FONT_STYLESHEET_URL`	Optional. Brand the sign-in screen

Sites hold no service-role key. The public key plus row-level security covers every read a site makes; anything needing more goes through the API.

API_URL must not end in a slash. The admin normalises it, but inline scripts in the base layout concatenate it raw, so a trailing slash produces //api/... requests.

The org

An org is a row in organizations with a settings JSON. Two settings matter on day one:

qa_mode: true turns inline editing on. Without it the bar reads that editing is off.
site_url is the canonical https:// address campaign links are minted against.

Members are rows in memberships (user_id, org_id, role of editor or admin). A person can belong to several orgs.

The admin mount

pages/admin.astro is a static shell that boots the admin. It passes the site’s schema and two switches:

mountAdmin(el, {
  dbUrl, publicKey, orgId, apiUrl,
  schema: ADMIN_SCHEMA,      // what the admin can add: lib/admin-schema.ts
  previewBase: "/preview/",  // the edit canvas loads the gated SSR preview route
  editChrome: "notch",       // the layout-safe edit chrome
});

The public site stays static. The preview route is server-rendered and membership-gated; it is what the edit canvas loads so a save shows on the next reload. Its gate caches allow decisions briefly and never caches a denial.

Local development

pnpm install
pnpm dev        # site + /admin on :4321
pnpm build      # static build to dist/

Edge middleware does not run under the dev server, so the template ships a dev-only Astro middleware that applies the same campaign-landing and private-site verdicts. It is compiled out of static builds.

Smoke test

Open /admin, sign in as a member of the org.
Press Edit, click the hero title, type, press Publish.
The bar reads Live. With no deploy hook set it reads Failed: No deploy hook, which is expected until the site has a rebuild address.

Start

Making content editable

Making content addable

Media

Next.js

Analytics SDK

Platform reference

Set up a site

What you start from

Environment

The org

The admin mount

Local development

Smoke test

Next steps

Anchors

Components

​What you start from

​Environment

​The org

​The admin mount

​Local development

​Smoke test

​Next steps

Anchors

Components

What you start from

Environment

The org

The admin mount

Local development

Smoke test

Next steps