Site backend (dynamic handlers)
Besides its static files, an uploaded website can have a real backend — small JavaScript handlers tied to individual addresses. Each handler is bound to a path and an HTTP method; when a visitor opens that address, Qubix runs the handler and returns whatever it builds — a page, a JSON answer, a redirect, a status code.
Use it when a page must do something on the server rather than just show static content: accept a lead via a POST request, answer a specific path with generated HTML, or send a redirect depending on the request. For ordinary static whitepages and landings you don't need this — leave the Backend tab empty and the website is served as plain files.
Open the Backend tab
A website card has three tabs at the top: Files, Backend, and Live. The active tab is saved in the address bar, so you can copy a link straight to a specific tab.
- Open the Websites section and click the website you need.
- Switch to the Backend tab.
If the website has no handlers yet, the list shows the hint that + new creates one from a template.
The Backend tab is only needed when the page must process something on the server. A purely static page works without any handlers.
Create a handler
- On the Backend tab, click + new in the top-left, above the handler list. A new handler is created from a ready-made template and opens in the editor.
🎬 GIF: clicking «+ new» and the template handler opening in the editor
- In the header form above the editor, set the path — the address the handler answers on. The field accepts a template with placeholders (for example,
/users/:id)::name— captures one path segment (for example,:idin/users/:idmatches/users/42);*— captures the rest of the path across several segments;**— matches the rest of the path without capturing it.
- Pick the method —
GET,POST,PUT,DELETE,PATCH,HEAD,OPTIONS, or ANY (answers any method). - Keep the enabled checkbox on so the handler works on the live site. Turn it off to keep a handler saved but inactive.
- In the central editor, write the handler code (see The handler code below).
- Click Save (or Cmd+S, on Windows — Ctrl+S).
In the list on the left, each handler is shown as its method and path (a handler with no method set is shown as ANY); a disabled one is marked accordingly.
If more than one handler could answer the same address, Qubix picks the most specific one — a handler with an exact path wins over one with a placeholder or a wildcard. So you can keep a precise handler next to a broad catch-all without them clashing.
The handler code
A handler is a JavaScript function that receives a request object — call it r — exposing the request (method, path, query and form arguments, headers, the captured path segments) and the response (set headers, return a status with a body, or a redirect). The template the editor starts from already shows the typical shape.
The editor is a full code editor with syntax highlighting and autocomplete: start typing r. and Qubix suggests the available request and response fields with their descriptions, so you don't have to keep them in your head.
Inside a handler you also have the shared Qubix toolset: read-only database queries, requests to external services, and state that persists between calls. These work the same way as in Scripts — see that article for the details. Outbound requests are only allowed to addresses the administrator put on the allowlist. Which tables and columns a query can reach is in Tables for sql queries.
The r object reference
Everything the handler reads from the request and uses to build the response.
Reading the request:
| Field | What it is |
|---|---|
r.method | The request's HTTP method (GET, POST, …) |
r.uri | The address the handler answered on (for example, /promo/123) |
r.rawUri | The full external address, including the service prefix |
r.args | The address and form parameters (key → value) |
r.params | Values captured from the path template (for example, id from /users/:id) |
r.requestBuffer | The request body as a string |
r.headersIn | The request headers |
r.remoteAddress | The visitor's IP |
r.variables | The click context: geo, click_id, sub1…sub5, lang |
r.session | The visitor session: get(key), set(key, value), delete(key) |
Building the response:
| Field / method | Action |
|---|---|
r.headersOut | The response headers (you can set and delete them) |
r.return(status, body?, location?) | Send the response; location is the redirect address |
r.log(...), r.warn(...), r.error(...) | Write to the run log (visible in the test runner) |
Crypto helpers
A handler also has crypto helpers:
| Method | What it does |
|---|---|
crypto.uuid() | A random identifier |
crypto.hmac(algo, key, data) | HMAC of data with key, hex-encoded; algo is 'sha256', 'sha1', or 'md5' |
Handy, for example, to sign data before sending it to an external service via fetch.
Test a handler
Each handler has a built-in test runner on the right of the editor — send a test request and see exactly what the handler answers, without touching the live site.
- Pick the method and enter the path to test (for example,
/users/42). - (Optional) Fill in the request inputs:
- Query (JSON) — query parameters as a JSON object;
- Body (raw) — the raw request body;
- geo and click_id — values passed to the handler as request variables.
- Click Run.
The result appears below:
- the response status (colored green / blue / red) and how long the run took;
- params — the values captured from the path template;
- Location — the redirect target, if the handler set one;
- the response headers and body;
- the console — everything the handler logged during the run.
If the request reaches or changes the handler's stored state, the panel also marks the session as touched.
Query (JSON) must be valid JSON. If it isn't, the test won't run and the field is highlighted — fix the JSON and click Run again.
Edit site files
The other half of the card is the Files tab — the website's static files (HTML, CSS, JS, images, fonts) in a tree on the left and a code editor on the right. Text files open with syntax highlighting; save with Save or Cmd+S (on Windows — Ctrl+S). Images, video, audio and other files get a preview or a download. You can drag files between folders and drop new ones from your computer.
A full breakdown of the Files tab is in Websites and Uploading a website.
Field and behavior notes
path — the address template the handler answers on. Supports :name (one segment), * (the rest, captured), and ** (the rest, not captured). The captured segments are available to the handler and shown as params in the test runner.
method — which HTTP method triggers the handler. ANY answers every method.
enabled — whether the handler runs on the live site. A disabled handler stays saved but is skipped.
+ new — creates a handler from the built-in template, ready to edit.