Before you can build anything in a page, two mechanical facts have to be right. Both are cheap to get wrong and expensive to debug, because neither failure produces an error.
Video tutorials for this topic
style.javascript, on the record
A page record carries a top-level style object, a sibling of data, with four slots:
| Slot | Injected as |
|---|---|
style.javascript | An inline <script> after the page's content |
style.css | An inline <style> |
style.scriptLinks | <script src> elements |
style.styleLinks | <link rel="stylesheet"> elements |
Your application goes in style.javascript. It arrives as a real script with a body and executes normally.
s, rec = req("GET", f"/repository/get/page/{SK}", token=t)
req("POST", f"/repository/update-partial/page/{SK}", {
"sk": SK,
"version": rec["version"],
"style": {"javascript": open("app.js").read()}, # beside "data", not inside it
}, token=t)This is the mistake that sends people looking for workarounds they do not need. A payload written to data.style.javascript is stored happily, returns 201, and never runs. There is no warning and no error.
Verify where it landed:
s, rec = req("GET", f"/repository/get/page/{SK}", token=t)
print("style" in rec) # True — correct
print("style" in rec.get("data", {})) # False — the wrong placeThere is no practical size limit. Print Oxygen's design studio is 113,115 characters in this field.
{"style": {}} clears it.
Keep the code in a real .js file in your source tree and have your deploy script read it in. Editing a large payload as a quoted string inside a JSON record is not something you want to do twice. The same goes for style.css.
The readiness gate
Here is the part that is not obvious and bites everybody once.
style.javascript is written out after the page's content, so on a full page load your markup already exists when it runs. But it runs while the document is still loading:
- before
window.appmintis mounted — the runtime is not there yet, and still is not atDOMContentLoaded - before anything the runtime renders —
data-sourcerows and bound values are not there yet
So the first thing your application does is wait for what it uses. The pattern is a self-rescheduling boot function:
(function boot() {
if (!document.getElementById('app-root') || !(window.appmint && window.appmint.cart)) {
return void setTimeout(boot, 30);
}
// From here: the DOM you need exists, and the runtime is up.
var $ = function (id) { return document.getElementById(id); };
// … your application
})();Two details make this work rather than half-work:
Gate on what you actually use. Checking window.appmint alone is not enough — namespaces mount progressively, so test the specific one you need (appmint.cart, appmint.reservation). And name a real element from your own markup, not document.body — the element check costs nothing and keeps the code safe if it is ever loaded some other way.
30ms, not 0. A tight reschedule burns CPU during hydration on slow devices for no gain. 30ms is imperceptible and cheap.
Do not replace the gate with DOMContentLoaded. The event does fire after style.javascript on a full load, but window.appmint is still not mounted when it does, so code that calls the runtime from that listener fails.
If it seems not to run
Put a flag at the very top, above the gate, while developing:
window.__APP_LOADED = true;
(function boot() { /* … */ })();Then on the rendered page:
window.__APP_LOADED // true → the field is wired; your gate never opened
// false → the field is in the wrong place, or emptyThat single check separates "my code is not being delivered" from "my code is delivered and waiting for something that never arrives", which are completely different problems.
When the <script> in your HTML runs
On the usual path the body of data.html is written straight into the server-rendered document, so on a full page load the browser runs each <script> in place, like a static file. Three things stop it, all silently:
- A
data-reactplaceholder in the body. The renderer rebuilds the body through its virtual DOM instead, and leaves every<script>in it out of the page. React presets render nothing now anyway, so remove the placeholder. - The
<head>. A head script runs, but ahead of the body markup — everygetElementByIdreturnsnull. - Client-side navigation. When a link rendered by the host itself (cart drawer, built-in store and content listings) swaps the page in without a new document load, no page script runs —
style.javascriptincluded. Plain<a href>links in your own HTML load a full page.
That is why your application still belongs in style.javascript: it does not depend on what else is in the markup, and it runs after the content.
What does survive
| In page HTML | Result |
|---|---|
<script> with a body | Runs in place on a full load; dropped if the page has a data-react placeholder |
<script src="…"> | Element survives and loads |
<style>, <link rel="stylesheet"> | Work normally |
onclick, onload and other handler attributes | Work — attributes survive intact |
<link rel="icon"> | Deliberately stripped; favicons come from the site record |
The fallback: an attribute bootstrap
There is one situation where style.javascript is not available to you: your pipeline produces HTML and nothing else. A plain <script> just before </body> now covers that on a full page load. The older route, still in use on existing pages, puts the whole payload on a 1×1 image's onload:
<img alt="" aria-hidden="true" width="1" height="1"
style="position:absolute;left:-9999px;top:0"
src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
onload='(function(){ /* your code */ })()'>The image decodes immediately from its data URI and the handler fires synchronously, with the surrounding DOM already present — so this route does not need the readiness gate for the DOM, though it still does for window.appmint.
Prefer style.javascript. The bootstrap carries real constraints: no single quotes anywhere in the payload, <, > and & must be HTML-escaped, and everything must be one expression in one attribute. It is a workaround, not a design.
The full rules, the generator, and the duplicate-bootstrap failure it can cause are in Run JavaScript on a hosted page.
Do not split handlers from your code
This applies to both routes and costs an afternoon the first time.
<!-- your code defines it… -->
<script>window.doThing = function (el) { /* … */ };</script>
<!-- …and markup calls it -->
<button onclick="doThing(this)">Go</button>On the deployed page doThing is undefined when the click fires, even when your code demonstrably ran. Attribute handlers on a hydrating host are not guaranteed to see globals assigned elsewhere.
Bind with addEventListener from inside your application. If you must use an inline handler, put the entire body in the attribute.
document.querySelectorAll('[data-tab]').forEach(function (el) {
el.addEventListener('click', function () { switchTo(el); });
});Make it idempotent
A page can render more than once on a hydrating host. Mark what you bind to:
var root = $('app-root');
if (root.dataset.bound) return;
root.dataset.bound = '1';And guard any request separately, so a double event cannot produce two records:
if (form.dataset.sending) return;
form.dataset.sending = '1';
// … delete form.dataset.sending in the final .then()Checklist
- Code in top-level
style— confirmed by reading the record back - A readiness gate that names a real element and the specific namespace you use
- No reliance on
DOMContentLoaded - Listeners bound with
addEventListener, not globals called from markup - Bind guard on the root, send guard on each request
Next: The read/write asymmetry — what your application is allowed to persist.
