Kitten

This tutorial kicks off the Kitten Count series of tutorials (tutorials 2-9) that walk you through the basics of Kitten by building and evolving an interactive page to count kittens.

Topics covered

You know what’s better than one kitten? Many kittens!

If you were following along from the previous tutorial, rename your index.html file to index.page.js. Otherwise, create a new file called index.page.js and place the following static HTML into it:

<h1>Kitten</h1>
<p>đŸ±ïž</p>

Remember that to test your Kitten apps, you run kitten from the folder that contains your source code and you visit https://localhost in your web browser to see the result.

You should see an error similar to the following in your browser:

Kitten 500 SyntaxError: Unexpected token '&lt;'
(Did you put raw HTML inside a function by mistake instead of wrapping it in a kitten.html`` tagged template?). Stack trace. From your app. While running compileSourceTextModule
in node:internal/modules/esm/utils (line 318, column 16). Rest of the error is cut off.
Kitten is telling us it can’t render raw HTML inside a JavaScript page route. Fair enough, fluffy one.

Kitten can’t compile the page because it’s expecting JavaScript and we have plain old HTML in there. Kitten catches the error and tells us that we should wrap our HTML inside a kitten.html tagged template string.

So let’s do that.

Update the contents of your file to match the following:

kitten.html`
  <h1>Kitten</h1>
  <p>đŸ±ïž</p>
`

Now, when you save, you should see a different error:

Kitten 500 Error: Page route at /index.page.js missing default handler export.
Please ensure you’re exporting a default function (or kitten.Page subclass) from your page. e.g. export default function () { return kitten.html } Stack trace. From Kitten. While running PageRoute.initialise in /kitten-bundle.js (line 311882, column 13). Rest of the error is cut off.
Kitten’s error messages try to suggest solutions to your issues whenever they can.

Ah, so we need to export a function to act as our request handler for this page route.

Let’s follow Kitten’s instructions and create and export a default function and return our kitten.html from it:

export default function () {
  return kitten.html`
    <h1>Kitten</h1>
    <p>đŸ±</p>
  `
}

And this time, everything works. Our page route gets called and the kitten.html we return is displayed in the browser.

Screenshot of web page with a heading (Kitten) and an emoji of a kitten.
Yay, we’re back to everything working again
 but this time, in JavaScript.

We’re back to where we were in our static page example but, crucially, we now have a dynamic JavaScript that we can add not just markup but behaviour to.

So, let’s do just that and implement a very basic version of our counter by creating an integer variable in memory and using that to display not just one kitten but an increasing number of kittens as the page is reloaded.

let count = 1

export default function () {
  return kitten.html`
    <h1>Kitten count</h1>
    <p>${'đŸ±ïž'.repeat(count++)}</p>
  `
}

Now refresh the page to see the number of kittens increase each time you do.

Screenshot of our app where the page has been reloaded many times and is full of kitten emojis.
So! Many! Kittens!

✹ Ooh, magic! ✹

But how does it work?

A page in Kitten is written in plain old JavaScript (and hence the page.js extension).

Kitten uses file system routing.

So, in this example, your /index.page.js file is mapped to the root route (/) of your site.

A route in Kitten is just an exported default function inside of a JavaScript module. Any HTML you return from your route is sent to the browser.

You can also use TypeScript by naming your pages using the page.ts extension.

Since Kitten pages – and components, etc., as you’ll see later – are just JavaScript/TypeScript, you don’t need any extra tooling to make things with Kitten. Your editor of choice will likely already know how to work with JavaScript/TypeScript, HTML, and CSS or can be easily configured to do so.

Although we’re not making use of them here, page routes are also passed properties (or “props”) in a parameter object. We could have written the function signature of our page route like this and had access to properties on the incoming HTTP request and even ended the response in different ways (e.g., by redirecting to a different page instead of returning kitten.html):

export default function ({ request, response }) {
  // 

}

Note that routes in Kitten take a parameter object (notice they are surrounded by { 
 }) instead of positional parameters which you might be familiar with from more traditional frameworks like Polka, Express, etc. Parameter objects make it easier to read code and are also used elsewhere in Kitten (components and fragments, the onConnect() handler, etc.)

You write your HTML inside of kitten.html tagged template literals. These are just standard JavaScript template literals (template strings) that get passed through a special global function called kitten.html that performs Kitten-specific magic.

Important security note: Part of that magic relates to the security of your apps. Kitten’s kitten.html tagged template literal sanitises any content you interpolate into your templates by default. This is important in avoiding cross-site-scripting (XSS) attacks. Kitten does the right thing by default when you use kitten.html. If you forget to use it and return a snippet of HTML in a plain JavaScript string, Kitten escapes it, shows it as text, and logs a warning. From an HTTP route, such as a .get or .post route, Kitten serves it as plain text, but htmx still swaps it into a page as HTML, so return kitten.html from a route too.

Demystifying things further

Take a look at the title of the tab in your browser. Do you see that it reads “Kitten count”?

That’s odd, you didn’t tell Kitten to set the title of the page but if you look at the source code of the page, you’ll see that it’s set in the <head> of your page as:

<title>Kitten count</title>

How’d that happen?

Well, Kitten tries to do the right thing by default. So, if you don’t set a title for your page, it tries to derive one for you by looking to see if there is a <h1> tag on your page and using that if there is. It might not be perfect but it’s better than nothing if all you’re doing is coding up a quick example.

But what if you want to set your own title?

Enter, the page tag.

The <page> tag

Kitten has a special tag called <page> that you can use to set commonly found elements in the heads of your pages (lang, title, charset, icon, and viewport) as well as to include the libraries that Kitten has first-class support for (HTMX, HTMX idiomorph extension, HTMX WebSocket extension, Alpine.js, and Water.css).

To use it, you simply include the tag anywhere on a page (or fragment or component):

let count = 1

export default () => kitten.html`
  <page title='Kitten count example'>

  <h1>Kitten count</h1>
  <p>${'đŸ±ïž'.repeat(count++)}</p>
`

If you look in your browser now, you’ll see that the title you supplied is shown instead of the default one derived from the <h1> element.

Before we end this version of the example, let’s add one little attribute (css) to our <page> tag for a quick win:

<page css title='Kitten count example'>

Notice how the page looks nicer with an easy-to-read sans-serif font and a max-width on the body, etc.

The css attribute of the <page> tag tells Kitten to include the Water.css CSS library. This is a semantic CSS library, which means that as long as you use semantic HTML, it will provide you with good baseline usable styles, as well as automatic light and dark mode support.

Test it out! Switch your computer’s colour scheme from light mode to dark mode and see your page adapt to it.

You can also use the <page> tag to add classes to the body tag. e.g.,

<page bodyClass='someClass someOtherClass'>

In addition to the <html> tag’s lang attribute, the regular <head> settings, and supported libraries, you can also use the syntax-highlighter attribute to automatically use the default highlight.js light and dark mode themes (the WCAG AA accessible Measured light and dark themes) for code blocks rendered from Markdown sections (<markdown>
</markdown>) in your code. If you want to choose your own theme instead, you can override default themes by manually adding any of the roughly 500 highlight.js themes that exist to your project and specify the relative or absolute URL to them in the syntax-highlighter-theme-light and syntax-highlighter-theme-dark attributes.

You’ll see later that you can set anything you want in the head of your pages using the special HEAD slot (<content for='HEAD'>
</content>) but the <page> tag should let you set the most common things you need when making Small Web sites and apps with Kitten.

As you can see, Kitten is very easy to get started with. But if you’re planning on creating an application that you see yourself supporting for a long time, you might be wondering about maintainability. Specifically, what if we want to make our code easier to write and debug by implementing type safety?

Kitten has you covered


Next tutorial: Type Safety

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.