Quick Start
WARNING
It’s best recommended to start a project with the npm create kita
command, as it generates a boilerplate with graceful shutdown, resource monitoring, and other useful features.
First of all, make sure you are using Node.js >= 20.
Kita relies on a lot of newer features and APIs that are not available in older versions.
node -v
# v20.0.0 ✅
2
Automatic Installation
You can start a new Kita project with a single command:
npm create kita
Currently, you can choose between two templates:
Kita: A normal backend project using Fastify
Kita & JSX & Tailwind: A frontend project using Fastify and @kitajs/html
Once done, you should see the newly created folder in your directory.
cd project
Start a development server with:
npm dev
Test it out!
Visit http://localhost:1227/reference
in your browser to see the generated OpenAPI documentation.
Read our code recipes for more information on how to customize your project.
Minimal Installation
If you already have an existing project and just want to add Kita, here’s how you can do it in the least intrusive way possible.
- First, install the necessary dependencies:
npm i -D @kitajs/cli @kitajs/ts-plugin
npm i @kitajs/runtime fastify
2
- Add the Kita plugin to your
tsconfig.json
for the best possible experience:
{
"compilerOptions": {
"plugins": [{ "name": "@kitajs/ts-plugin" }]
}
}
2
3
4
5
If you’re using VSCode, by default it doesn’t use the TypeScript installed in your
node_modules
. To do so, create a.vscode/settings.json
file and add the following content:Refer to the official documentation for more information.
{
"typescript.tsdk": "node_modules/typescript/lib",
"typescript.enablePromptUseWorkspaceTsdk": true
}
2
3
4
- Update the
build
scripts in yourpackage.json
to runkita build
before transpiling the code:
{
"scripts": {
"build": "kita build && tsc",
"start": "node dist/index.js"
}
}
2
3
4
5
6
- Add the
src/index.ts
file with the following content:
// This is required to be executed before any import or require
globalThis.KITA_PROJECT_ROOT ??= __dirname;
import { Kita } from '@kitajs/runtime'; // [!code focus]
import fastify from 'fastify';
const app = fastify();
app.register(Kita); // [!code focus]
app.listen({ port: 3000 });
2
If you have a formatter or linter configured that doesn’t handle globalThis.KITA_PROJECT_ROOT ??= __dirname;
well at the root of your main file.
We recommend that you move this line to src/prelude.ts
and import it into your main file:
// This is required to be executed before any import or require
globalThis.KITA_PROJECT_ROOT ??= __dirname;
import './prelude'; // [!code ++]
// ...
2
// This is required to be executed before any import or require
globalThis.KITA_PROJECT_ROOT ??= __dirname; // [!code ++]
2
- Create your first route in
src/routes/hello.ts
:
export function get() {
return { hello: 'world' };
}
2
3
- 🎉
You’re ready to run your server:
npm run build
npm start
2
Test it out!
Visit http://localhost:3000/reference
in your browser to see the documentation.
Read our code recipes for more information on how to customize your project.
TIP
This minimal installation does not include features like resource monitoring and graceful shutdown that are essential for a production server.
Generate a template with the npm kita create
command to have a complete project and perform your partial migration from there if necessary.