Quickstart

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:

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.

Open a terminal in the repo root (the folder above demo/) and run:

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 http://localhost:8000/. 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 http://localhost:8000/builder.php). 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

Click the Save button in the top-right of the builder chrome. The browser POSTs the current canvas state to demo/backend/save.php, which writes the JSON to the buyer-package's demo/uploads/ folder. The Save button briefly flashes "Saved ✓".

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 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. If you see a 500, click the request → Response tab — the PHP error is rendered there. The most common cause is demo/uploads/ lacking write permission. chmod 755 demo/uploads (macOS / Linux) fixes it.

If you hit something this list doesn't cover, the 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 500 → chmod 755 demo/uploads on macOS / Linux, or check demo/backend/save.php error log.

What's next?

• → Architecture — the mental model behind the three containers + page hierarchy.
• 🔗 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/ 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.