Getting started

Install & projects

Getting the app, creating a project, opening one, and what a project folder contains.

sitereal is a desktop app. It runs on your machine, opens a folder, and edits the project in it — nothing is uploaded anywhere and no account is required to build.

Requirements

The app — macOS, Windows or Linux.
Node.js 20+ — a sitereal project is an Astro project, so npm install and npm run dev are what run it. The app can install dependencies for you when it creates a project.
git (optional but assumed) — every new project gets its own repository.

The project manager

The window you land in is a grid of your projects. Each card is led by a picture of the project's home page, rendered by the engine and photographed offscreen — no dev server, nothing on screen. A project that has never been opened under this build draws a mark from its own name instead.

Pin a project to keep it at the front. Pins are ordering only; nothing on disk moves.
Forget a project to take it off the list. It deletes nothing but the picture.
Settings — the last entry in the rail — holds what belongs to the app, not to a site: your GitHub account, where new projects are created, and which build is running. A project's own settings live inside the project window.

Creating a project

Give it a name and a location. sitereal writes a complete Astro project:

my-site/
  site.sitereal            the project document — everything the builder knows
  package.json             astro dev / build / preview
  astro.config.mjs
  tsconfig.json
  .gitignore               includes .sitereal/ — engine state, one machine
  .mcp.json                registers this project's MCP server
  .vscode/                 the Astro extension + a dev-server launch config
  public/favicon.svg
  src/
    layouts/PlainBase.astro   the layout emitted pages extend — yours from here on
    pages/                    emitted pages
    components/               emitted components

Then it runs git init and npm install. The repository matters more than it looks: without one, a git command run inside the folder walks up until it finds a repository — so a project created inside another checkout would quietly commit into that one.

If you have marked a preset as the one new projects start from, it is applied before the project file is first written — the project has never existed without your design system. The site's own identity (name, URL, social links) is never carried by a preset. See Presets.

Opening a project

Open any folder that contains a site.sitereal. Opening starts the engine for that project: a small local server that reads and writes the project document and emits files. It records its port in .sitereal/engine.json, which is gitignored because it describes one process on one machine.

Older projects that still have a .strata/ sidecar folder are migrated to a single site.sitereal the first time they are opened.

Running the site

The builder canvas is not a dev server — it renders the page itself, instantly, without a build. To see the real thing, run Astro:

npm run dev        # http://localhost:4321
npm run build      # a static site in dist/
npm run preview    # serve what you just built

Both views are the same files. Editing src/pages/about.astro by hand and editing it on the canvas are two ways of touching one thing — with the exception of the generated files listed in Files, git & deploy, which are rewritten from the project document on every save.

Using a local build

If you are developing sitereal itself, Develop → Use Local Build… points the installed app at a locally built UI and engine. It swaps those two, never the installed shell — anything new on the preload bridge needs a real reinstall of the desktop app.