Reference sections
Reference › JavaScript and TypeScript
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:
Install the Kitten Types module as a development dependency:
npm install --save-dev @small-web/kitten-typesEither:
a. Add
// @ts-checkto the tops of your JavaScript pages, orb. Create a jsconfig.json file.
The
kitten add kitten-typescommand 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
jsconfigin place oftsconfigin their names:- jsconfig.json (the root file)
- jsconfig.server.json
- jsconfig.client.json
- client-globals.d.ts
It also sets your
typecheckscript tonpx tsc -b jsconfig.json. (Without a file name, thetsc -bcommand looks for tsconfig.json.)Note that if you already have a jsconfig.json file of your own, the
kitten add kitten-typescommand 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.jsonand./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:
Install Kitten Types (@small-web/kitten-types) as a development-time dependency.
npm install --save-dev @small-web/kitten-typesCreate 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:
- client-side scripts (.client.ts files)
- any other .ts file that isn’t a server-side Kitten file type
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.
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 {}