Index âș 2. Dynamic Pages
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
- Dynamic pages (.page.js files).
- File system-based routing.
- The
kitten.htmltagged template string. - Security and string sanitisation.
- The
<page>tag.
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 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:

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.

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.

âš 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