Ship & extend
Files, git & deploy
What is generated, what is yours, and how a sitereal project ships.
A sitereal project is a repository. Everything the builder does ends up as a file change you can read, review and revert — which means the way you ship it is the way you already ship Astro sites.
Files
Files is the whole project as a tree, in the same editor code mode puts beside the canvas: tabs, saving as you type, undo per file, and a preview for pictures, video, SVG, Markdown and HTML. The + at the head of the tree makes a new file or folder. See Code mode & files.

The files sitereal writes are plain Astro, and you can edit them anywhere — in your editor, in Claude Code, or on a teammate’s machine. What it writes, and what happens when one of them is changed somewhere else:
| Path | Written from | Edited elsewhere |
|---|---|---|
src/pages/<route>.astro | the page | read back into the page |
src/components/<Name>.astro | the component | read back, its styles and script included |
src/layouts/<Name>Layout.astro | a template | read back into the template |
src/components/popups/, src/components/snippets/ | pop-ups, HTML snippets | read back |
src/styles/generated/** | global styles, pages, templates, pop-ups, the design system | read back — in framework.css only the variables; a rule written there moves to global.css by itself |
src/data/<slug>.json, src/entries/<slug>/ | a content type | read back — write a new entry file to add an entry |
[...<name>Entry].astro under src/pages/ | a public content type or data source | the entry design is read back; the route’s own lines stay sitereal’s |
public/scripts/*.js, src/data/sources/*.js, form endpoints | the runtimes, data sources, forms | kept as you wrote them, but they come from a setting — change the setting |
public/robots.txt, public/sitemap.xml | SEO settings, while marked as generated | yours once the marker is gone |
site.sitereal | the engine | never by hand — go through the app or the tools |
Everything else is yours and is never touched: src/layouts/PlainBase.astro, your own components, astro.config.mjs, package.json. A new .astro file you put under src/pages/ becomes a page: shaped like the others it is an ordinary page; anything else stays its own file and opens on the canvas with nothing put around it.
Editing outside sitereal
sitereal watches the files it wrote. When one changes on disk — a save in your editor or in code mode, an agent’s edit, a git pull — it is read back into the project a moment later and the canvas follows. A file you formatted by hand keeps its formatting: when the canvas changes it later, only the lines that changed are rewritten.
Nothing is written over, and nothing is asked. When the canvas and the file both changed, the two are merged line by line; where both changed the same line, the edit in the file wins, and the canvas’s version is one ⌘Z away. Lines the canvas has no place for — a tag you added to the head, a value on <Base> — stay in the file. A file that does not read yet, or says something only a setting can, stays exactly as written and is listed under not on canvas in the top bar, which opens it in code mode at the line. Delete a page’s file and the page goes too, with History keeping it; any other generated file is written again.
Working in a team? Update everybody to the same version. A project saved by a newer sitereal opens read-only in an older one instead of being written back in an older shape, and a collection stored as entry files looks empty to a version before 0.4.0 until it is opened in 0.4.0 again — nothing is lost.
Version control
The everyday four live in main and Publish in the top bar, the History’s Git tab, and Settings → Repository:
- Branches — see local and remote, switch, create, merge. Switching keeps your unfinished work with the branch it belongs to and hands it back when you return; a merge is reviewed file by file before it is made (see the Git tab). A branch can open a pull request, with the host’s preview link. When the branch you switch to asks for other packages — one trying a new Astro, say — they are installed for it, and the preview and the build check wait until they are in.
- Commit — in the Git tab, or in Settings → Publish, where the changed files are listed above the message, every one ticked: untick what should wait, or keep a new file out for good.
- Pull — fetch and bring the current branch up to date. When both sides have commits, the Git tab opens Review merge instead.
- Push — Push to GitHub under Publish commits what changed and pushes it, in one click. The Git tab’s Push sends only the commits there are.
Every project gets a history of its own when it is created. That is not a nicety: it is what keeps a project made inside another folder with a history from quietly committing into that one.
History in the rail has two tabs. Snapshots is every save, kept on a ref of its own so it never touches your branch: for each entry, how the page looked, the real patch of what that save wrote, and which branch it was on — with your own commits in the same list. Restoring one page or the whole document is a save like any other, so it can be undone the same way.
The Git tab
Git is the repository as GitHub sees it. Its rail holds Pull from GitHub and Push to GitHub with what is waiting each way, the Branches with how far each is ahead of or behind yours, a box to commit to the branch you are on, the Releases (the repository’s tags), and the Commits as a graph you can filter by branch.
- A commit or a release opens as the site looked then, with the patch it made. Restore page and Restore everything write it back as a save, never a checkout, so it shows up in Snapshots and can be undone. Start a branch here makes a branch at that commit and switches to it.
- A branch shows the commits only it has, with Switch to it, Review merge into yours, and Delete branch. The copy on GitHub stays.
- Review merge lists every file the branch brings. Where both branches changed the same file, it shows the final code with each disagreement in place: keep one side, the other or both, or edit the result by hand. Nothing is merged until every question has an answer. Merge in Settings → Repository opens the same review.
GitHub
Connect an account under Settings → Repository and you can create a repository, pick an existing one, or paste a remote URL. Only the pointer to the remote changes — disconnecting leaves your history and your files exactly where they are.
Identity, on the same screen, shows the three accounts that decide who a commit is from: the GitHub account the app is signed in as, whoever git’s credential helper pushes as, and the author written into the commit. When they disagree, a commit or push stops once and says so.
What a good diff looks like
Because site.sitereal is written with a stable key order, a one-field change is a one-line diff rather than a reshuffle of the file. And because pages emit as ordinary .astro, a pull request shows the actual markup that changed:
- <h1 builder-data-element="heading" class="hero__title">Hello</h1>
+ <h1 builder-data-element="heading" class="hero__title">Hello, world</h1>Reviewers do not need sitereal to review a sitereal change.
Publishing
The Publish button in the top bar pushes to GitHub, publishes straight to a host, or both: Vercel, Netlify, Cloudflare or your own web hosting over FTPS or SFTP, with previews and rolling back. Which one it does is chosen under Publish settings. All of it is in Publishing & hosts.
To look at the site before it goes out, press ▶ in the top bar: the page opens in your browser exactly as it will ship.
Commit site.sitereal. It is what makes the project editable on another machine — and it is the one file that has to travel with the repo for the builder to open it as a project.