docs
/
Building on Appmint

Where your code goes

The page record's style.javascript field, the readiness gate every page app needs, and when the script tag in your HTML runs and when it doesn't.

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.

style.javascript, on the record

A page record carries a top-level style object, a sibling of data, with four slots:

SlotInjected as
style.javascriptAn inline <script> after the page's content
style.cssAn 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)
`style` is top-level. `data.style` is read by nothing.

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 place

There 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.appmint is mounted — the runtime is not there yet, and still is not at DOMContentLoaded
  • before anything the runtime renders — data-source rows 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 empty

That 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-react placeholder 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 — every getElementById returns null.
  • 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.javascript included. 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 HTMLResult
<script> with a bodyRuns 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 attributesWork — 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.