elements
Blog Demos UI Docs Pricing
Elements Manual
  • Getting Started
    • Project Layout
    • At a Glance
    • More Patterns
    • Database and Migrations
    • Conventions
    • Deploy, Licensing, Support
  • CLI
  • Build
  • Browser
  • Packages
  • TypeScript
  • Elements HTML
  • Assets
  • RPC
  • Router
  • Session
  • Database
  • Migrations
  • LiveTable
  • Channel
  • Jobs
  • Email
  • Payments
  • JSON
  • Async
  • Style
  • UI
  • JSOC
  • Config
  • Tests
  • Logs
  • Deploy
  • Editors
  • Recipes
  • Licenses
Manual / Getting Started

Getting Started

elements man start

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: Check The Server, Then 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.

Check whether the app 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 wait for it in the foreground. [ -f .elements/run ] is false forever against a directory, and a loop on it hangs against an app that is already serving. If it is already serving, use that url and say nothing to the user about starting it.

If nothing is running, tell the user in one line to type elements start in a terminal in the project (in VS Code, the terminal above the chat). In their own terminal they see the build state while you work, a green Ok or a red Error, so typing it is a habit for them to keep. It opens the page in your tool's own browser where it has one, the VS Code extension's or any that $BROWSER names. Do not ask who should start it.

If your harness wakes you when a background command ends, start a wait for the app as one before that line, so you hear when it is up: until cat .elements/run/*.json 2>/dev/null; do sleep 0.2; done. When it ends, say it is running and give its url as a link to click, in your reply or in the terminal. In the Claude desktop app a clicked link opens the Browser pane. Never open the page yourself first: the welcome page celebrates on its first load, and that load is the user's. In a Claude desktop terminal elements start leaves the system browser shut for this.

Create asked you to open one terminal tab in the project. If your tool cannot open one, a terminal the user opens starts in some other folder, so the one line carries the move and how to open one: the real key or menu item for a terminal in the app you run in, never a placeholder, then cd <project path> && elements start. Without a background wait, skip it: elements start opens their browser itself.

If it fails for them, or they ask you to start it, run elements start & in the project. Use & and not nohup, so it stops with your session rather than leaving a server they cannot find. Never start a second server beside one that is serving, and never stop or restart one the user started.

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 (opens in a new tab).

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.

Topics

start/layout What elements create writes and where your code goes.start/at-a-glance The whole framework on one page: route, template, rpc, job, LiveTable, test.start/patterns Worked fragments for sessions, forms, validation, email, and scheduled work.start/database The bundled Postgres, writing a migration, running it.start/conventions How Elements differs from what you would guess, and the conventions its source follows.start/deploy Shipping the app, load balancing, licensing, and support.
Next Project Layout
Product
Manual Pricing Compare
Company
History Contact
Legal
Privacy Policy Acceptable Use Terms License Agreement
© Elements Dev Corporation 2026