Kitten

Technical Manual sections

Rendering turns the files of an app into HTML in three steps: the loader compiles each file into a JavaScript module, kitten.html renders what the module returns, and the page route wraps the result in a page shell.

The loader script compiles each of Kitten’s file types (e.g., .page.js, .component.ts, and .page.md) into a JavaScript module. For Markdown pages, Markdown fragments, and HTML fragments, the loader (src/lib/loader.ts) calls the markdownModule() function (src/lib/markdownModule.ts), which parses the front matter of a Markdown page as YAML.

src/lib/html.ts implements kitten.html, the tagged template that every page, component, and fragment returns. It is Kitten’s merged and modified copy of xhtm (which parses the template into a tree) and vhtml (which renders the tree as HTML). It also renders <markdown> blocks, and it returns a promise when one of the values it interpolates is a promise, an async component, or a stateful component.

kitten.html returns a frozen array of strings that Kitten marks as markup (src/lib/markup.ts). Two WeakSets record which values are markup and which are trusted (kitten.markAsTrusted()), so a plain string can never pass for either. Kitten checks each interpolated value against the place it lands in:

(The Interpolated values section of the reference lists these rules from an author’s point of view.)

src/lib/markdown.ts configures Kitten’s MarkdownIt instance (kitten.md) and its plugins:

Both the loader and the main process use it.

PageRoute wraps what a page returns in a full HTML document. It chooses the client-side libraries to load from the attributes of the page’s <page> tag (a live page always loads htmx and its idiomorph and WebSocket extensions, and a page that uses hx-boost always loads htmx), and always loads kitten-1.js, which configures htmx and defines the browser’s kitten global. The libraries come from lib/ and node_modules/, and the build copies them into /🐱/library/ (see Build and release). In production, Kitten serves the minified versions of htmx, the idiomorph extension, Kitten’s Alpine.js module, and Water.css (kitten.libraries in src/lib/globals.ts).

In development, the page shell also loads the hot reload script, and Kitten runs the html-validate validator over the page and adds its results to the page (src/routes/lib/validator.ts).

Source code:

The Glossary in the reference defines the kinds of pages you author in Kitten. They differ in when Kitten renders them:

Cached pages, which would be dynamic pages that Kitten renders only once, are not implemented yet (see Cached pages).

The dynamic page is the default page type in Kitten.

All you have to do to create a dynamic page is to export a default function that returns kitten.html.

For example, the following displays the current date and time every time the page is reloaded:

export default () => kitten.html`
  <h1>${new Date()}</h1>
`

Dynamic pages are rendered again (have their default export, or their html() method, called and the result sent to the browser) on every GET request.

That’s all there is to dynamic pages.

All HTTP routes – e.g., GET, POST, etc. – are also rendered on every hit. If you want to cache their results, you have to implement your own caching mechanism. (Which you could do using Kitten’s built-in database support.)

Not implemented yet, see issue #365.

Cached pages are dynamic pages that export a special flag that makes Kitten render the page only the first time it is hit:

// Cache response until server restarts.
export const cache = true

This will make Kitten cache the page until the server restarts (which will happen, for example, if Kitten or the app is updated).

Optionally, you can also set the cache value to the time, in minutes, that you want content cached for:

// Cache response for a day.
export const cache = 24 /* hours */ * 60 /* minutes */

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.