Template API Reference

Async Iterator

The render result contains an async iterator, which allows consumption through a for await statement.

import Template from "./template.marko";

for await (const chunk of Template.render({})) {
  // send the html chunk somewhere.
}

Each iteration yields the HTML flushed since the previous one; a render with no asynchronous content yields a single chunk.

Abandoning the loop with break, return, or a thrown exception aborts a pending render with the error Iterator returned before consumed., and a later pull rejects with it. The iterator's throw(reason) method aborts with the given reason instead.

Pipe

The .pipe() method in the render result object sends the HTML into a NodeJS stream.Writable. Any object with write(chunk) and end() serves as a target, and a flush() method, if present, is called after every chunk to keep a buffering transform such as zlib.createGzip() streaming.

import Template from "./template.marko";
import http from "node:http";

http
  .createServer((req, res) => {
    // Stream rendered html into the server response.
    Template.render({}).pipe(res);
  })
  .listen(3000);

ReadableStream

The .toReadable() method in the render result object returns a WHATWG ReadableStream. This can be used in environments that support web apis, eg in a web worker.

const webHTMLResponse = new Response(Template.render({}).toReadable(), {
  headers: { "content-type": "text/html" },
});

Reading is deferred to the stream's first pull, so wrapping it in a Response that is never read leaves the result unconsumed. Cancelling the stream aborts the render with the cancellation reason.

Thenable

The render result is a thenable, so the .then(), .catch() or .finally() methods return a Promise<string> that resolves with a buffered HTML string. This may be handled implicitly with the await keyword.

const html = await Template.render({});

const html = Template.render({}).toString();

Render Result

The .mount() API returns an object with helpers used to update and destroy the instance of the template and DOM that was built, and to access its return value.

const instance = template.mount({ name: "foo" }, document.body);

instance.update({ name: "bar" });

instance.destroy();

<let/color="#ff8000">
<input type="color" value:=color>
<return=color valueChange(newColor) {
  color = newColor;
}>

<let/color="#ff8000">
<input type="color" value:=color>
<return=color valueChange(newColor) { color = newColor }>

let/color="#ff8000"
input type="color" value:=color
return=color valueChange(newColor) {
  color = newColor;
}

let/color="#ff8000"
input type="color" value:=color
return=color valueChange(newColor) { color = newColor }

import ColorPicker from "./color-picker.marko";

const instance = ColorPicker.mount({}, document.body);

instance.value; // The currently selected color

instance.value = "#0080ff";

$global.serializedGlobals

string[] | Record<string, boolean> | undefined

$global stays on the server. Naming a property here also writes its value into the page, which makes it readable as $global from client code such as an event handler.

Template.render({
  $global: {
    locale: "en-GB",
    apiToken: "secret",
    serializedGlobals: ["locale"],
  },
});

Above, $global.locale can be read in the browser and $global.apiToken cannot. An object selects the same properties and suits a list assembled in more than one place, which is how Marko Run exposes it as ctx.serializedGlobals.

serializedGlobals: { locale: true, apiToken: false }

A named property holding undefined is left out.

$global.signal

AbortSignal | undefined

When signal is included in $global, Marko will listen to it and automatically clean up any pending async rendering activity when it is aborted.

This is used to, for example, prevent continued rendering after an incoming request is aborted.

$global.cspNonce

string | undefined

Marko writes this CSP nonce as the nonce attribute on the <script> and <style> elements it renders: the <html-script> and <html-style> tags, the <style> element rendered for a <style> tag with dynamic values, and the inline scripts written to stream and resume the page.

An explicit nonce, written on the element or supplied by a spread, takes precedence over the injected value.

A <script> or <style> rendered in the browser reads cspNonce from the client $global, which holds the properties named in serializedGlobals.

const cspNonce = crypto.randomUUID();

res.setHeader(
  "Content-Security-Policy",
  `script-src 'nonce-${cspNonce}'; style-src 'nonce-${cspNonce}'`,
);

Template.render({
  $global: { cspNonce, serializedGlobals: ["cspNonce"] },
}).pipe(res);

$global.renderId

string | undefined

The renderId isolates one render from every other render sharing a runtime in the same document. It always has a value, "_" by default.

A template with no html, head, or body tag, compiled with the linkAssets compiler option that @marko/vite configures, instead gets a fresh random value on every render() call, so such renders never collide in one document. mount() always defaults to "_".

Set an explicit value when several renders of a page template share a document, so each one resumes against its own data.

Template.render({
  $global: { renderId: "cart" },
});

$global.runtimeId

string | undefined

The runtimeId names the global variable holding the resume data for every render in the document, and defaults to "M". Overriding it isolates multiple copies of Marko sharing a page. It follows the same identifier rule as renderId.

Server and browser builds must agree on the value, so it belongs in the bundler configuration rather than an individual render. @marko/vite accepts a runtimeId option and bakes it into the generated entries, which apply it to $global.runtimeId.