Getting Started

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

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: Start The Server First, Then Work In The Open

Run elements start & as your first move in a new project, before you read a man page or open a file. It takes a couple of seconds and opens the app in the user's browser, so there is a working page on screen while you are still reading. Do not save it for when you have something to show.

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:

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.