# Kitten types

Type-safety for [Kitten](https://kitten.small-web.org) 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](https://codeberg.org/kitten/app).

## Install

```shell
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:

```js
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](https://www.typescriptlang.org/).

### JavaScript

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

2. *Either* add `@ts-check` to the tops of your JavaScript files or [add a jsconfig.json file](https://kitten.small-web.org/reference/#jsconfig-json) 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:

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

To add type annotations to your project, you can use [JSDoc](https://jsdoc.app/).

### TypeScript

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

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

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

2. [Create a tsconfig.json file.](https://kitten.small-web.org/reference/#tsconfig-json)

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

   ```ts
   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:

```ts
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:

```js
// @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](https://kitten.small-web.org/tutorials/type-safety/).

## Database type safety

Kitten by default has at least two [databases](https://kitten.small-web.org/reference/#database) 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](https://kitten.small-web.org/tutorials/database-app-modules/).

## Relationship to `@small-web/kitten`

> 💡 The older [`@small-web/kitten`](https://www.npmjs.com/package/@small-web/kitten) module [has now been deprecated](#relationship-to-small-web-kitten). 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](https://small-tech.org) is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.

## License

Copyright © 2026-present [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org)
Released under [AGPL 3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).