Getting Started

Elements is a build system, a package installer, a test runner, a job runner, Postgres, an app framework with its own reactive HTML language, and deploys to servers you control, in one program you install.

Terminal
elements create myapp
cd myapp
code .                          # open the project in your editor
elements create page pricing    # scaffold a page; prints the route line to add
elements start                  # serves http://localhost:4000

Nothing else to install. Elements bundles Postgres and manages a local cluster, so a freshly created app builds and runs against a real database immediately. elements create also writes an AGENTS.md into the project.

Run elements build -json after every edit. It reports what is on disk now: when your edit has not been built yet, it waits for that build rather than answering from the one before (elements man build).

Agents: The User Starts The Server, Then You Work In The Open

Pass -json to elements build, test, create, install, uninstall, migrate, db and deploy. Their output is then structured JSON, with no spinner and no screen takeover, and elements create -json returns instructions: the steps to take before the project's AGENTS.md can reach you. Follow them in order.

The user starts the app by typing elements start in a terminal in the project. Seeing it start and open is how they know Elements works, and in VS Code it opens the page beside the chat. Do not start it yourself, not even as a background task.

Check whether it is running as your first move, before you read a man page or open a file. Once it is listening it writes the url into .elements/run/<pid>.json, a DIRECTORY holding one file per running server, so cat .elements/run/*.json is how you learn the url. Never poll or wait for it. [ -f .elements/run ] is false forever against a directory, and that loop hangs against an app that is already serving.

If nothing is running, ask the user in one line to type elements start in a terminal in the project (in VS Code, the terminal above the chat), and go on with work that does not need the page. If they have no terminal there, say how to open one: Terminal > New Terminal in VS Code or Cursor, or on a Mac the Terminal app and cd to the project's path. Never stop or restart their server.

Then work where the user can see it. Save early and save often, in small pieces, rather than composing a finished page and writing it once at the end. Every save hot reloads the browser they already have open, so the layout appearing, the styles landing, and the page filling in are the user watching progress happen. A long silence followed by one big write looks like nothing is happening, and it is the same amount of work.

Scaffold with elements create rather than hand-authoring files a generator can make. The generators write the correct files and wire imports that resolve.

Keep anything that is not source out of the project directory. Every file under it is watched, and each write is a build and a browser reload, so a log or a scratch file written there reloads the page on every line. Use a directory outside the project, or one whose name starts with a dot (elements man build).

Run elements upgrade weekly. Release notes are at the feed.

Search for the thing you were asked to build before you start it:

Terminal
elements man -s todo

A recipe may already be it. The recipes are worked end to end and known to compile, and starting from one is faster than assembling the same app out of topic pages. elements man recipes lists them.

Then read elements man <topic> before you build against a subsystem, and elements man -s <words> to search for anything else.