Getting started
How sitereal works
site.sitereal, the engine, and the real Astro files that ship.
Three things make up a sitereal project: one document that holds what the builder knows, an engine that turns that document into files, and the files themselves — which are the site.
One file: site.sitereal
Everything the visual interface needs lives in a single JSON document at the project root: site settings, the design system, variables, global styles, installed fonts, components, templates, popups, forms, snippets, content types, data sources, media metadata and every page's tree.
{
"format": "sitereal",
"version": 2,
"site": { "name": "My site", "lang": "en" },
"framework": { "enabled": true, "config": { "...": "..." } },
"variables": [],
"styles": [],
"components": [],
"templates": [],
"snippets": [],
"pages": { "index": { "route": "index", "root": [] } }
}It is committed with the project, so the project moves, copies, versions and diffs as a unit. It is the editor’s memory — element ids, layer names, the settings a file cannot say — while the content lives in the files themselves: change a page in another editor and sitereal reads it back.
The site never reads this file. Nothing emitted may import or fetch it. Delete it and astro build still produces the same site — you lose visual editing, not the site.
The engine
Opening a project starts a local server. It is the only writer of site.sitereal, and it owns emitting: when you save a page it writes that page's .astro file and its CSS; when you change something project-wide — the design system, variables, global styles, templates, snippets, site settings — it re-emits every page, because those things reach into all of them. It also watches what it wrote: an edit made in another editor, in code mode or by an agent is read back into the project, and when the canvas changed the same file meanwhile the two are merged rather than one overwriting the other.
The same engine serves the builder, the tools an AI assistant uses, and the pictures on your project cards. There is one implementation of every operation.
What a page is
A page is a tree of nodes. One node looks like this:
{
"id": "section-hero",
"tag": "section",
"name": "Hero",
"classes": ["hero"],
"attrs": { "builder-data-element": "section" },
"children": []
}idis stable. It is what the canvas selects and what per-element CSS is keyed to.nameis the layer name — what the tree shows, and what BEM class generation reads.attrsholds every attribute except class, includingbuilder-data-element.textis text content;htmlis raw inner markup, for things that own their markup (an SVG, a highlighted code sample).
The page tree becomes the <main> of the emitted file. A template supplies whatever wraps it.
What gets written
| Path | Written by | Edited by hand |
|---|---|---|
src/pages/<route>.astro | every page save | yes — read back into the page |
src/components/<Name>.astro | component save | yes — read back |
src/layouts/<Name>Layout.astro | template save | yes — read back |
src/components/popups/, src/components/snippets/ | pop-up and snippet saves | yes — read back |
src/styles/generated/global.css, pages/, templates/, popups/ | style saves | yes — read back |
src/styles/generated/framework.css | design-system save | the variables only — a rule written there moves to global.css by itself |
src/data/<slug>.json, src/entries/<slug>/ | content types | yes — read back |
entry routes, src/components/sitereal/*.astro | public content types and sources | the entry design is read back |
public/scripts/*.js — nav, motion, popup, carousel, form, video, consent, search | when a page needs one | no — an edit is kept, never overwritten, but these come from a setting |
src/data/sources/*.js, form endpoints | data sources, forms | no — kept, never overwritten |
src/db/, drizzle.config.ts | switching a content type to the database | yes — an ordinary Drizzle project |
public/robots.txt, public/sitemap.xml | SEO settings, while marked as generated | no |
src/layouts/PlainBase.astro | scaffold, once | yes — it is your file |
| everything else in the repo | you | yes |
The rule: sitereal writes these files from the project document and reads back what you change in them. When both sides changed a file, the changes are merged; a file it cannot read back yet is left exactly as you wrote it. Everything else is yours, and sitereal will not touch it.
Why builder-data-element
Every element carries an attribute naming what it is — section, container, heading, nav-link. The design system styles those attributes:
:where([builder-data-element="section"]) {
padding-block: var(--section-space-m);
padding-inline: var(--site-padding);
}Two consequences worth understanding. First, structural styling never depends on a class you might rename — the attribute is the contract, your classes stay yours. Second, :where() contributes zero specificity, so any class or id you write overrides the design system without !important and without caring about source order.
The loop you actually work in
- You edit on the canvas or in a panel.
- The page goes to the engine a moment after you stop typing (
⌘Ssends it at once). - The engine writes
site.siterealand emits the files. - The browser preview (▶ in the top bar), if you have it open, reloads with what changed.
- A few seconds later the engine runs a real
astro buildin the background, and the dot in the top bar says whether the site still builds. - Or edit the file instead — in code mode beside the canvas, or in your own editor: the engine reads it back a moment after you save, and the canvas follows. See Code mode & files.
There is no build step of ours in that path, and no cache to invalidate.