Kitten

Reference sections

Internally, Kitten uses the latest Node.js LTS binary as its runtime (currently Node 24 LTS.).

You can quickly get started with Kitten using plain old JavaScript.

Kitten does not have a build stage, nor does it require any scaffolding.

So you’ve started hacking together some JavaScript and you want to add type safety to your site or app.

It’s easy:

kitten init js

The kitten init command also declares the Kitten API version the app supports in package.json (the engines.kitten field), which a deployed app’s updates follow; see Versioning.

kitten add kitten-types

If you’d rather do things manually so you know exactly what’s happening:

  1. Install the Kitten Types module as a development dependency:

    npm install --save-dev @small-web/kitten-types
    
  2. Either:

    a. Add // @ts-check to the tops of your JavaScript pages, or

    b. Create a jsconfig.json file.

    The kitten add kitten-types command sets up a JavaScript project if your project has a jsconfig.json file and no tsconfig.json file. Otherwise, it sets up a TypeScript project.

    For a JavaScript project, it writes the files listed under tsconfig.json, with jsconfig in place of tsconfig in their names:

    • jsconfig.json (the root file)
    • jsconfig.server.json
    • jsconfig.client.json
    • client-globals.d.ts

    It also sets your typecheck script to npx tsc -b jsconfig.json. (Without a file name, the tsc -b command looks for tsconfig.json.)

    Note that if you already have a jsconfig.json file of your own, the kitten add kitten-types command doesn’t change it. Instead, it shows a warning and doesn’t write any of these files. Either move your jsconfig.json file aside and run the command again, or set things up by hand.

    To set things up by hand, copy the files listed under tsconfig.json. Rename tsconfig.json, tsconfig.server.json, and tsconfig.client.json to jsconfig.json, jsconfig.server.json, and jsconfig.client.json. Then change the two paths in jsconfig.json to ./jsconfig.server.json and ./jsconfig.client.json.

That’s it!

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

Kitten also has TypeScript support without requiring a build step (your .ts files work exactly like your .js files).

kitten init

(Or kitten init ts but ts is the default and hence redundant.)

The kitten init command also declares the Kitten API version the app supports in package.json (the engines.kitten field), which a deployed app’s updates follow; see Versioning.

kitten add kitten-types

If you’d rather do things manually so you know exactly what’s happening:

The process for enabling type safety for TypeScript projects has just one extra step than that for JavaScript projects:

  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.

Kitten automatically transpiles TypeScript files it serves to the browser to JavaScript.

These include:

The client program type checks every file that isn’t a Kitten server file type, using the browser’s types. So if you write code that only runs on the server, put it in a .script.js or .script.ts file. Kitten never serves those files, and the client program leaves them out.

Note that the client program also leaves out tests and test folders, but Kitten still serves the files in them as usual.

Program

A collection of SourceFiles and a set of compilation options that represent a compilation unit. The program is the main entry point to the type system and code generation.

– TypeScript Compiler Notes

This is the recommended set of configuration files for Kitten, implementing the libraries recommended for Node 24 by the tsconfig/bases project for the server program. The kitten init command writes all of them, and the npm run typecheck command runs tsc -b, which checks both programs. (For a JavaScript project with a jsconfig.json file, see For an existing project under Type safety.)

tsconfig.json, tsconfig.server.json, tsconfig.client.json, and client-globals.d.ts
// The server and the client program have different kitten globals.
{ "files": [], "references": [{ "path": "./tsconfig.server.json" }, { "path": "./tsconfig.client.json" }] }
{
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "./.tsbuildinfo/server",

    "target": "ES2025",
    "lib": ["ES2025", "ESNext.Array", "ESNext.Error"],
    "module": "Preserve",
    "moduleDetection": "force",

    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,

    "skipLibCheck": true,
    "allowJs": true,
    "checkJs": true
  },
  "exclude": ["node_modules", "**/*.client.js", "**/*.client.ts", "client-globals.d.ts"]
}
{
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "./.tsbuildinfo/client",

    "target": "ES2025",
    "lib": ["ES2025", "DOM", "DOM.Iterable"],
    "module": "Preserve",
    "moduleDetection": "force",

    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,

    "skipLibCheck": true,
    "allowJs": true,
    "checkJs": true
  },
  "include": ["**/*"],
  "exclude": ["node_modules", "**/app_modules/**", "**/__archive__*/**", "**/tests/**", "**/test/**", "**/*.test.*", "**/*.spec.*", "globals.d.ts", "**/*.get.js", "**/*.head.js", "**/*.patch.js", "**/*.options.js", "**/*.connect.js", "**/*.delete.js", "**/*.trace.js", "**/*.post.js", "**/*.put.js", "**/*.get.ts", "**/*.head.ts", "**/*.patch.ts", "**/*.options.ts", "**/*.connect.ts", "**/*.delete.ts", "**/*.trace.ts", "**/*.post.ts", "**/*.put.ts", "**/*.socket.js", "**/*.socket.ts", "**/*.page.js", "**/*.page.ts", "**/*.page.md", "**/*.component.js", "**/*.fragment.js", "**/*.component.ts", "**/*.fragment.ts", "**/*.fragment.html", "**/*.fragment.css", "**/*.fragment.md", "**/*.layout.js", "**/*.script.js", "**/*.styles.js", "**/*.layout.ts", "**/*.script.ts", "**/*.styles.ts"]
}
import '@small-web/kitten-types/client.d.ts'
export {}

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.