Rendering · JavaScript API

render turns a template into a string. Pass the template's name and the variables it should see.

const html = await kiln.render("pages/post", {
	route: { path: "/blog/hello/" },
	post,
});

render always returns a promise, but only waits when a template calls something async.
If anything goes wrong, the promise rejects and no partial output is returned. See Errors and checks.
Generate TypeScript types to have your editor check template names and data.
To send the page while it renders, use renderStream.

Render options

The third argument sets options for one render:

Option	Description
`state`	Data for this request, passed to functions made with `withRender`. See Request data
`locale`	Overrides the environment's locale
`timeZone`	Overrides the environment's time zone
`signal`	An `AbortSignal`. Kiln stops the render as soon as it is aborted, even while it waits for your code
`islands`	Defers `island` tags with `deferIslands()`, or streams them with `streamIslands()` and `renderStream`. Without it, islands render in place

const html = await kiln.render("pages/home", context, {
	locale: "fr-FR",
	timeZone: "Europe/Paris",
	signal: request.signal,
});

Rendering one block

renderBlock renders a single block of a template. Use it to send a fragment of a page, for example in reply to an htmx or fetch request.

const results = await kiln.renderBlock("pages/search", "results", { query });

Kiln picks the block the full page would use, so a page's version wins over its layout's.
Top-level set tags in the page still run, so data the page loads is available.
The block doesn't see variables the layout creates around it, such as a for loop's variable.
Asking for a block that doesn't exist is an error.

Kiln compiles each template the first time it is used, then keeps the compiled version. The loader is called once per template name. If loading or compiling fails, Kiln tries again on the next render.

Kiln also remembers the last thousand or so names the loader didn't find, so a missing template isn't asked for on every render.

When a template changes or is added, for example after an edit in your CMS, call invalidate:

kiln.invalidate("pages/home"); // one template
kiln.invalidate(); // all templates

Render options

Rendering one block

Caching