You extracted the BuilderJS ZIP. You want to know: *does it actually run, and where do I click to see the editor?* This page answers both — every step here is a verifiable observable, no engine theory until you've seen it boot. ## What's in the ZIP After unzipping, the folder layout you care about is short: ``` builderjs/ ├── demo/ ← what you'll open in your browser │ ├── index.php ← showcase home (the page that links everywhere else) │ ├── builder.php ← the live builder editor │ ├── docs/ ← these docs you're reading right now │ ├── examples/ ← 35 runnable code examples │ ├── themes/default/ ← the canonical theme (templates + samples) │ └── backend/ ← save / asset-upload / export PHP handlers └── dist/ ├── builder.js ← the engine bundle (pre-built, ~280 KB) └── builder.css ← engine stylesheet (~35 KB) ``` Everything you need to run the demo is already inside `builderjs/demo/`. The pre-built engine bundle in `dist/` ships with the ZIP — you do **not** need `npm install` to demo, develop themes, ship samples, or wire a backend. (You only need npm if you intend to rebuild `src/`, which is a separate workstream.) ## Boot the package You need PHP **8.1 or newer** — that's it. macOS, Linux, and Windows-WSL all ship with a recent PHP, or install via Homebrew (`brew install php`), apt (`sudo apt install php`), or [windows.php.net](https://windows.php.net/). Open a terminal in the **repo root** (the folder *above* `demo/`) and run: ```bash php -S localhost:8000 -t demo/ ``` Three things happen: 1. PHP's built-in dev server starts on port `8000`. 2. The `-t demo/` flag tells it to serve files from `demo/` as the document root (so `/index.php` resolves to `demo/index.php`). 3. The terminal logs `Listening on http://localhost:8000`. In your browser, open . You should see the showcase home with a **Try the builder** call-to-action. ## Open the live builder Click **Try the builder** (or navigate directly to ). The page loads with three regions: - **Left rail** — the *widgets palette*. Drag any widget onto the canvas. - **Center** — the *canvas*. The "Minimal" sample renders here. Click any element to select it. - **Right rail** — the *settings panel*. Edit attributes of the currently-selected element (text, color, padding, link…). Make any change — type into the heading, swap an image, drag a Heading widget into a new spot. The canvas updates live; nothing is persisted yet. ## Save and reload Saving writes to your disk, so the package ships with it **switched off** — the builder shows a **Backend off** pill next to Save, and a save is answered with `403`. For this local run, stop the server (`Ctrl-C`) and start it again with the demo backend on: ```bash BJS_DEMO_BACKEND=open php -S localhost:8000 -t demo/ ``` `open` means "no sign-in" — right for a server only you can reach. Before you put the demo anywhere others can reach it, read [Switch the demo backend on](/docs/13-backend/#switch-the-demo-backend-on). Reload the builder and click the **Save** button in the top-right of the chrome. The browser POSTs the current canvas state to `demo/backend/save.php`, which writes it back over the sample you opened (`demo/themes/default/master/sample/email/Minimal.json`). A "Saved" toast confirms it. Reload the page (`Cmd-R` / `F5`). The builder loads with **the same content you saved**. That's the round-trip that proves three things at once: 1. The engine serialises the canvas via `builder.getData()` (a plain JSON object). 2. The shipped `save.php` stores it. 3. On reload, the engine restores it via `builder.load(themeJson, themeTemplates, themeConfigData, mediaUrl)`. You've now seen every part of the integration surface a buyer typically wires: load · edit · save · reload. The next docs explain *how* each piece fits together so you can swap the demo's `save.php` for your own backend, your own theme, or your own custom widgets. ## Common boot-time errors > **Port 8000 already in use** — `Failed to listen on localhost:8000 (reason: Address already in use)`. Either stop the other server (`lsof -i :8000` to find it on macOS / Linux) or pick a different port: `php -S localhost:8765 -t demo/`. Every URL in these docs uses `8000`; substitute as you go. > **`php: command not found`** — install PHP. macOS Homebrew: `brew install php`. Ubuntu / Debian: `sudo apt install php`. Windows: download from [windows.php.net](https://windows.php.net/) and add `php.exe` to your `PATH`. Verify with `php -v`. > **`PHP version too old`** — BuilderJS's demo backend uses `declare(strict_types=1)` + named arguments + nullsafe operators (`$x?->y`). Run `php -v`; if it reports < 8.1, upgrade. The engine itself runs in any modern browser; the version constraint is on the demo's PHP backend only. > **`Class 'ZipArchive' not found`** — only triggered if you click **Export → ZIP** in the builder. Install the PHP zip extension: macOS Homebrew already includes it; Ubuntu `sudo apt install php-zip`; Windows uncomment `extension=zip` in `php.ini`. Restart `php -S` after. > **The canvas is blank** — usually a network error loading `dist/builder.js` or `dist/builder.css`. Open the browser DevTools network tab and reload. If a file 404s, the package extracted incompletely; re-extract from the ZIP. > **Save button does nothing** — open DevTools → Network. The Save click should fire a POST to `/backend/save.php`. A **403** means the demo backend is still switched off — restart the server with `BJS_DEMO_BACKEND=open` (see *Save and reload* above). If you see a 500, click the request → Response tab — the PHP error is rendered there. The most common cause is the theme tree lacking write permission. `chmod -R u+w demo/themes` (macOS / Linux) fixes it. If you hit something this list doesn't cover, the [FAQ](/docs/15-faq/) has 12 more cases with debug recipes — including engine-source pointers for the rare "I read every doc and it's still wrong" tier. ## Did you make it? You should now be able to: - ✅ Run `php -S localhost:8000 -t demo/` and reach the showcase home at `/`. - ✅ Open the builder at `/builder.php` and edit the Minimal sample. - ✅ Save your changes and confirm they survive a reload. If a step didn't work: - 🩹 *Boot fails before any browser step* → re-read **Common boot-time errors** above. PHP version + missing extensions cover ~80 % of first-run issues. - 🩹 *Builder loads but the canvas is blank* → check DevTools network tab for `dist/builder.js` 404. Re-extract the ZIP. - 🩹 *Save returns 403* → the demo backend is switched off; restart with `BJS_DEMO_BACKEND=open php -S localhost:8000 -t demo/`. - 🩹 *Save returns 500* → `chmod -R u+w demo/themes` on macOS / Linux, or check `demo/backend/save.php` error log. What's next? - → [Architecture](/docs/02-architecture/) — the mental model behind the three containers + page hierarchy. - 🔗 [`examples/basic/1-quickstart/`](/examples/basic/1-quickstart/) — the runnable version of every snippet on this page (and the standalone `snippet.php` you can copy verbatim into your own project). Stuck on something the troubleshooter doesn't cover? - 🐛 grep `src/includes/Builder.js` for the API name in question — the engine source is the canonical truth. - 🐛 open [`/examples/basic/1-quickstart/`](/examples/basic/1-quickstart/) and re-read its walkthrough — every example pins its surface end-to-end. - 🐛 file an issue with: extracted ZIP version, PHP version, exact command + exact output. Reproducible reports get fixes; vibes-bug-reports stall.