Kitten types

Type-safety for Kitten apps and sites.

This is a types-only package. It declares the global kitten namespace (via declare global) and exports reusable Kitten types you can use to annotate your own code.

The types are automatically generated from the Kitten source code.

Install

npm install --save-dev @small-web/kitten-types

Use

Kitten exposes a global kitten namespace at runtime.

This makes it easy to get up and running when learning, prototyping, or just building something quick without having to worry about type safety (you don’t have to import any packages to get started with building Kitten apps).

Here’s a quick Hello World example that greets you with a smiley face:

export default () => kitten.html`
  <h1>Hello, world! <${kitten.icons.Smiley} /></h1>
`

💡 Put the above code in a file called index.page.js and run kitten from the same directory if you want to follow along.

While it works, you won’t get language intelligence for the kitten global, so you won’t be able to, for example, see all the other possible kitten.icons you could be using.

How you add language intelligence and static type checking for Kitten to your project differs based on whether you’re using JavaScript or TypeScript.

JavaScript

1. Install Kitten Types (@small-web/kitten-types) as a development-time dependency.

2. Either add @ts-check to the tops of your JavaScript files or add a jsconfig.json file to your project to enable type checking.

That’s it!

In a JavaScript project, the global types will automatically be picked up by the TypeScript language server.

So your example becomes the following with full type safety and intelligence:

// @ts-check
export default () => kitten.html`
  <h1>Hello, world! <${kitten.icons.Smiley} /></h1>
`

To add type annotations to your project, you can use JSDoc.

TypeScript

There’s one extra step (compared to JavaScript) when using TypeScript.

1. Install Kitten Types (@small-web/kitten-types) as a development-time dependency.

   npm install --save-dev @small-web/kitten-types

2. Create a tsconfig.json file.

3. Create a globals.d.ts file in your project:

   import '@small-web/kitten-types'
   export {}

That’s it!

The global kitten type information will now be picked up by your editor.

Importing types for explicit annotations

When you need to annotate function parameters, etc., import the types directly.

In TypeScript:

import type { KittenRequest, KittenResponse } from '@small-web/kitten-types'

export default ({ request, response }: { request: KittenRequest, response: KittenResponse }) =>
  kitten.html`<h1>Kitten</h1>`

And, in JavaScript:

// @ts-check
/**
  @param {{
    request: import('@small-web/kitten-types').KittenRequest,
    response: import('@small-web/kitten-types').KittenResponse
  }} parameters
*/
export default ({ request, response }) => kitten.html`
  <h1>Kitten</h1>
`

🔗 For more help in using this module, please see the Kitten Type Safety Tutorial.

Database type safety

Kitten by default has at least two databases per project:

An internal database called _db and a custom one for you to use in your project called db.

This package provides a type-safe _db export for the internal database as the structure is well known.

If you want type safety for your custom project database, please create and use a type-safe database app module.

🔗 For a more in-depth look into database type safety, please see the Database App Modules Kitten Tutorial.

Relationship to @small-web/kitten

💡 The older @small-web/kitten module has now been deprecated. You should use this module for new projects and plan on migrating existing projects over to it going forward.

The older globals module cast the members of globalThis.kitten at runtime and provided type safety for JavaScript projects (prior to TypeScript support being added to Kitten).

This was problematic as a discrepency between Kitten and the globals module was not just a missing completion in your editor but could break your app at runtime.

The @small-web/kitten package is now deprecated but kept available for backwards compatibility. It also now sources all of its types from this package (@small-web/kitten-types).

New projects should use this types-only package and existing projects should be migrated over.

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.

License

Copyright © 2026-present Aral Balkan, Small Technology Foundation Released under AGPL 3.0.